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Introduction 


Organization of This Book 


This book is the definitive reference manual for mental ray® versions 3.1 through 3.4. It begins 
with a brief overview over the features of mental ray and continues with the specifications of 
the mental ray scene description language and the mental ray shader interface. All material is 
presented in reference form, organized by grammar elements and C function call, rather than by 
feature set. It is intended for translator writers and shader writers who are familiar with the C 
and C++ programming languages. 


For a tutorial-style description of mental ray, refer to the book “Rendering with mental ray” 
[Driemeyer 05], which is intended for non-programmers who want to effectively use mental 
ray without concern for its internal structure and programming interfaces. The functionality of 
mental ray is presented in much greater detail there. 


This book is organized in six chapters and two appendices: 


Chapter 1 gives a brief overview over the functionality of mental ray. 

Chapter 2 describes the scene language in detail. This chapter is organized by language 
unit. 

Chapter 3 explains how custom shaders and Phenomena™ are written, and documents the 


shader call interface. 

Chapter 4 describes the extended geometry shader interface. 

Chapter 5 describes the integration interface of the library version of mental ray. This 
chapter is useful only for application developers, and not part of the standard 


mental ray manual. 


Chapter 6 contains porting guidelines for users and shader writers upgrading from mental 
ray 1.9 to mental ray 2.x, from 2.1 to 3.0, and from 3.0 to 3.1. 


Appendix A describes the command-line interface of mental ray. 


2 Introduction 


AppendixB contains the source code of mental ray’s scene language parser. 
The mental ray versions described in this book are 3.1.4, 3.2.4, and 3.4.2. 


Throughout this book, features only available in mental ray 2.1 but not mental ray 3.x are marked 
by superscript “2.1”, features only available in mental ray 3.0 and later are marked “3.x”, features 
available in mental ray 3.1 and later are marked “3.1”, and so on up to features introduced with 
mental ray 3.4 which are marked “3.4”. 


Introduction to mental ray 


mental ray is a general-purpose renderer which creates images of exceptional quality and achieves 
high performance through the exploitation of parallelism on both multiprocessor machines and 
across networks of machines. 


The software uses advanced rendering acceleration techniques such as a scanline rendering 
algorithm for primary visible surface determination and the BSP (binary space partitioning) 
algorithm for secondary rays. These algorithms can be fine-tuned by optional user-settable 
parameters to achieve even higher performance than normally achieved by the built-in automatic 
scene cost analysis. 


mental ray supports caustics and global illumination simulation using the Photon Map™ method. 
Caustics caused by multiple reflections and/or refractions, caustics that are themselves reflected or 
refracted, and volume caustics are supported. Complete, physically correct simulation of general 
global illumination is also supported: any combination of diffuse, glossy, and specular reflection 
and transmission can be simulated, such as color bleeding caused by diffuse interreflections, and 
multiple volume scattering. 


mental ray has been designed to take full advantage of parallel hardware, including both thread 
parallelism ona single machine, and process level parallelism across networks of machines, and on 
massively parallel distributed-memory systems. mental ray takes advantage of thread parallelism 
automatically; the use of other machines on the network as render slaves may be configured by 
the user. The renderer balances the computational load among the available processors using a 
distributed shared database that distributes parts of the scene in an optimal way based on demand. 


mental ray can be combined with any suitable modeling and/or animation system via the .mi 
file format, or by integrating the library version into the modeling and animation system, or by 
combining the library with a translator that reads the modeling system’s native file format. mental 
ray has been fully integrated into SOFTIMAGE XSI and Alias Maya, and supports all rendering 
features of Version 3.x for SGI and Windows NT’, as well as additional rendering functionality 
which is made easily accessible through corresponding enhancements to the user interface. mental 
ray is also the rendering component of Dassault Systemes’ CATIA and Solidworks systems. 
Specifically, it is integrated into the CATIA Visualization Studio, supporting all geometric and 


'N'T is used here to refer to all Windows 95, 98, ME, NT, 2000, XP, and other variants. In fact Windows 2000 reports 
its version as NT 5.0 and Windows XP as NT 5.1. 
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nongeometric CATIA entities. mental ray is also available as a plug-in for Autodesk 3ds max 3.0 
and later. Finally, mental ray is available as a stand-alone program for batch-mode rendering. 


In addition, translators are currently available for Alias Advanced Visualizer, Alias Power 


Animator, RenderMan RIB, Side Effects’ Prisms, IGES, and the DESIRE format. 


mental ray is a library for integration into third-party software, as well as for integration in 
standalone versions that read a variety of scene formats. In the standard standalone version, input 
is via a scene file in ASCII format. The .mi format is the native scene description format of mental 
raySupported geometric primitives include polygons, and trimmed free-form surfaces. Polygons 
may be concave or convex and may contain holes. All geometry may be procedurally displaced. 
Together with the mental matter™ product, subdivision surfaces’ are supported as well. 


Free-form surfaces may be input in non-uniform rational B-spline (NURB), Bézier, Taylor 
monomial, or cardinal form, or through the use of basis matrices. Free-form surfaces may 
be of arbitrary degree. The geometry of free-form surfaces may be further modified by the 
application of trimming curves and displacement maps. Trimming curves need not have the same 
representation as the surface. Surfaces are triangulated internally using a variety of available 
approximation techniques which may be dependent on or independent of the distance from the 
surface to the camera. 


Connectivity information between free-form surfaces can be given which will stitch surfaces 
together and close gaps. If the connectivity is unknown, it can be automatically determined at 
run-time. 


mental ray supports incremental changes to the scene database. Only the parts of the scene that 
change from one frame to the next need to be redefined. This feature allows mental ray to optimize 
scene tessellation, preparation, acceleration data structure management, and network transfers, 
taking advantage of the time coherency of the animation. 


The functionality of mental ray may be extended through runtime linking of user-supplied C 
or C++ subroutines, called shaders. This feature can be used to create geometric elements at 
runtime of the renderer, procedural textures, including bump and displacement maps, materials, 
atmosphere and other volume rendering effects, environments, camera lenses, and light sources. 
The user has access to a convenient environment of supporting functions and macros for use 
in writing shaders. The parameters of a user-provided shader can be freely chosen with name 
and type; user-defined shaders are not restricted to a list of predefined parameters. Available 
parameter types include integers, scalars, vectors, colors, textures, light sources, arrays, and 
nested structures. When a user-defined shader is called, mental ray will provide parameter values 
according to standard C calling conventions. 


Standard material shader libraries provide a rich variety of parameters for describing material 
properties, including ambient color, diffuse color, specular color, transmission and shadow colors, 
a specular exponent, reflectivity, and transparency coefficients, and an index of refraction. The 
standard physics shader library adds global illumination effects and other physically correct 
simulations such as indirect illumination, translucency, glossy reflections, true diffuse light 
transport (a sub-function of global illumination that is often called “radiosity”), and color 
bleeding. Bump mapping and displacement mapping are supported as well These parameters 
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are interpreted by the shader specified for the material. All material parameters may be mapped 
with one or more textures or other shaders, simply by building shader graphs by connecting 
shader inputs and shader outputs. 


All these illumination effects are not hard-coded features of mental ray, but flexible user-defined 
shader features. New illumination features, or variations of existing features, can be added simply 
by writing or modifying shaders. 


Light passing through the space surrounding objects, as well as light passing through solid 
objects, is modified according to volume shaders, which allow the creation of effects such as fog 
and non-homogeneous transparency effects and visible caustics beams. In addition to standard 
materialuenvironment maps, a global environment map can be specified that provides a solid 
background for rays leaving the scene. 


The standard base, physics, and contour shader libraries are available as source code from 
ftp://ftp.mentalimages.com/pub/shaders/. 


mental ray can generate a variety of output formats, including common picture file formats and 
special-purpose formats for depth maps and label channels. Alpha channels and both 8 and 16 
bits per component are supported, as well as a 32-bit floating-point component mode and RGBE 
HDR?" (high dynamic range) images. User-supplied functions can be applied to the rendered 


image before it is written to disk. 


Contour lines can be placed at discontinuities of depth or surface orientation, between different 
materials, or where the color contrast is highi, simply by using an appropriate contour shader. 
The contour lines are anti-aliased, and there can be several levels of contours created by reflection 
or seen through semitransparent materials. The contours can be different for each material, and 
some materials can have no contours at all. The color and thickness of the contours can depend 
on geometry, position, illumination, material, frame number, and various other parameters as 
determined by the shader. The resulting image may be output as a pure contour image, a contour 
image composited onto the regular image (in raster form in any of the supported formats), or as 
a PostScript file. 


Phenomena consist of one or more cooperating shaders or shader trees (actually, shader DAGs; 
a DAG is a directed acyclic graph). A phenomenon consists of an “interface node” that looks 
exactly like a regular shader to the outside, and in fact may be a regular shader, but generally 
it will contain a link to a shader DAG. mental ray takes care of integrating all aspects of the 
phenomenon into the scene, which may include the introduction or modification of geometry, 
introduction of lenses, environments, and compile options, and other shaders and parameters. 


The Phenomenon concept is conceived to unify — by packaging and hiding complexity — all 
those seemingly disparate approaches, techniques, and tricks, most notably (but not limited to) 
the concept of a shader, which are characteristic for today’s state of the art in high-end 3D 
Animation and in Digital Special Effects production. The aim is to provide a comprehensive, 
coherent, and consistent foundation for the reproduction of all visual phenomena by means of 
rendering. The Phenomenon concept provides the missing framework for the completion of the 
definition of a scene for the purpose of rendering in a unified manner. 
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WWW Resources 


mental ray’s homepage is http://www.mentalimages.com. For errata and changes that 
were made after this book went into print, and downloadable .mi scene file examples, see 
http://www.mentalimages.com/books.html. 


The source code for the shader libraries included with the mental ray distribution is available on 
ftp://ftp.mentalimages.com/pub/. See the README file at this location for the exact path. 


mental images runs several discussion mailing lists; see http: //www.mentalimages.com for 
details and instructions for subscribing and posting (follow the Forum link). 


The Los Angeles mental ray user’s group collects useful information on http://www. lamrug.org/. 
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Chapter 1 


Functionality 


mental ray offers all the features traditionally expected of photorealistic rendering, together with 
functionality not found in most rendering software. The following sections describe parallelism, 
free-form surface input geometry, edge merging, and various input entities such as materials, 
texture mapping and light sources, and global illumination features such as caustics. 


1.1. Parallelism 


mental ray has been designed to take full advantage of parallel hardware. On multiprocessor 
machines that provide the necessary facilities, it automatically exploits thread parallelism where 
multiple threads of execution access shared memory. No user intervention is required to take 
advantage of this type of parallelism. mental ray is also capable of exploiting thread and process 
level parallelism where multiple threads or processes cooperate in the rendering of a single image 
but do not share memory. This is done using a distributed shared database that provides demand- 
driven transparent sharing of database items on multiple systems.' This allows parallel execution 
across a network of computers. 


mental ray 3.2 and later also support hyperthreading on Intel Pentium 4 processors that support 
it. Hyperthreading is a technique that runs a second thread, including a separate process 
counter, on a single CPU chip to exploit otherwise idle execution units on the chip. Since this 
increases memory access frequency and reduces locality of reference, hyperthreading achieves a 
performance increase of only about 15-25%. Early machines with hyperthreading support are 
not very reliable, so most vendors disable hyperthreading in their hardware, BIOS, or operating 
system even though the CPU supports it. mental ray will not pull a license for a hyperthreading 
companion thread. 


'The parallel rendering technology which is required for the support of distributed shared databases has been originally 
developed by mental images as part of the ESPRIT Project 6173 Design by Simulation and Rendering on Parallel 
Architectures (DESIRE). See [Herken 94]. 
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1.1.1. Geometry Caching 


Load balancing and distribution is achieved by subdividing the entire rendering operation into a 
large number of small jobs. Jobs may perform a wide variety of operations: tessellating a portion 
of a surface, loading a portion of a texture, casting a bundle of rays, rendering a small section 
of the image, balancing a photon map, and many others. mental ray 2.1 executed these jobs in 
phases: first the scene is read into memory, then all objects are tessellated, then photon maps and 
shadow maps are generated, and finally the image is rendered. Each phase involves execution of 
all the jobs required for successful completion of the phase. Jobs get distributed to all threads and 
all hosts that are available. 


mental ray 3.x is using finer-grain jobs, manages a dependency graph of jobs, and executes jobs 
on demand. There are no more phases; a job is simply executed when another job accesses data 
generated by that job. Data generated by jobs enters a memory pool called the geometry cache. 
(Actually, the cache manages almost all data stored in memory by mental ray, including textures, 
photons, images, etc, and not just geometry; the name geometry cache is mostly traditional.) Data 
can not only enter the cache but can also be deleted when memory fills up and the data has not 
been used for a while. 


Dynamic job execution and the geometry cache as the central hub of mental ray 3.x has several 
advantages: 


e rendering begins almost immediately, instead of having to wait for the completion of a 
possibly large number of preparation jobs. 


e data that is not used is not computed. For example, typically only parts of shadow maps 
are ever actually used; mental ray 3.x will only compute those parts and not waste time on 
creating the entire shadow map. Also, in fly-through scenes, only small parts of the scene 
are actually used for rendering. 


e not all data is used at the same time. mental ray 2.1 created all triangles, textures (except 
memory maps), shadow maps, and other data up front, just in case they will be used, and 
stored them all in memory at the same time for the entire rendering time. mental ray 3.x 
behaves differently: data enters the cache when needed, and may get displaced later when 
memory fills up. Memory usage rises smoothly up to the user-defined cache limit, and then 
stays there. 


e parallelism is enhanced in mental ray 3.x because threads no longer become idle near the 
end of each phase, and because job execution is completely independent of location and 
of other jobs, and can be freely scheduled all over the network to make use of available 
resources. 


e if the complexity of the scene exceeds the capacity of the system, system performance 
degrades gracefully instead of “hitting the wall” by failing or excessive disk swapping. This 
point is typically reached by mental ray 3.x far later, with scenes several times as large, than 
mental ray 2.1. 


In general, geometry caching has the effect of exploiting scene coherence very effectively. 
Frequently, mental ray 3.x achieves significantly higher speed at over 80% memory usage 
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reduction. Unlike traditional geometry caching methods, this advantage is not limited to scanline- 
only scenes; it works with all aspects of mental ray including ray tracing and global illumination. 
Since it exploits scene coherence, it works better if the scene does have a high degree of coherence, 
but its advantage remains even for less-coherent scenes, only reduced. The advantage of the cache 
degrades gracefully with less coherent scenes, instead of shutting off at some point. For example, 
scenes that make extensive use of global illumination, which by definition is global and less 
coherent, require a larger cache but still benefit from it. 


The host that reads or translates the scene, or runs front-end application software that mental ray 
is integrated in, is called the master host. The master host is responsible for connecting to all other 
hosts, called slave hosts. A slave host may also act as master host if an independent copy of mental 
ray is used by another user; systems do not become unavailable for other jobs if used as slaves. 
However, running a mental ray slave on a host may degrade the performance of independent 
interactive application programs such as modelers on that host significantly. If a slave host aborts, 
the entire network participating in the render (the master and all slaves) are notified and abort as 
well. mental ray periodically checks the health of all hosts on the master/slave network. 


The list of hosts to connect to is stored in the .rayhosts file. The first existing file of 
.ray2hosts (ray 2.x) or .ray3hosts (ray 3.x), .rayhosts, $HOME/.ray2hosts (ray 2.x) or 
$HOME/.ray3hosts (ray 3.x), $HOME/.rayhosts is used as .rayhosts file. Each line contains 
a hostname with an optional colon-separated port number of the service to connect to and 
an optional whitespace-separated parameter list that is passed to the host to supply additional 
command line parameters. Such a remote host is called a slave, while the main host that reads the 
.rayhosts file is called the master. The first line that literally matches the name of the master 
host is ignored; this allows all hosts on the network to share a single . rayhosts file, each ignoring 
the first reference to itself. Only masters ever access the host list. If the -hosts option is given to 
mental ray, the .rayhosts file is ignored, and the list of slave hosts is taken from the command 
line. In this case, no hosts are ignored. The library version of mental ray may get its host list 
directly from the application. 


1.1.2 Firewalls 


Since Windows machines are usually festering with viruses and other malware, it has become 
popular to install products called “firewalls” that prevent certain forms of network connections. 
A typical method to do this is stopping programs from initiating socket connections, often before 
the destination of the connection becomes known. The user then may or may not be presented 
with a popup window warning that a program has attempted to “open an Internet connection”. 


First, these programs are not firewalls. A firewall separates a trusted system or network from an 
untrusted network, so it must always be a separate box in between and may not be embedded 
software in the trusted zone. It has become a standard procedure for malware to detect and disable 
such “firewalls”, which makes a travesty of the concept. Still, they can do a lot of damage: 


mental ray, like many parallel programs, depends on socket connections, both for internal thread 
communication and for external connections to other programs such as external image viewers 
like zmf_disp, or slave hosts that contribute to rendering, or the license server on the local network. 
Those “firewalls” stop those as well, often claiming that “an Internet connection” was attempted, 
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preventing mental ray (or the application that it is built into) from starting up. mental ray is not 
given a chance to prevent this or even warn the user about what has just happened. 


mental ray 3.3.3 and higher attempt to work around a few of these problems by avoiding 
certain types of internal communication, including realtime image display using imf_disp, but 
the underlying problem caused by those “firewalls” cannot be fixed. The workaround mode is 
enabled in some integrations only. 


This is a Windows-specific problem, Unix and Linux do not suffer from this. 


1.2 Free-Form Surfaces 


mental ray supports free-form curves and surfaces in non-uniform rational B-spline (NURBS), 
Bézier, Taylor (monomial), cardinal or basis matrix form. Any of these forms may be rational 
and may be of degree up to twenty-one.” Surfaces may be trimmed. 


Internally, free-form surfaces are triangulated (approximated) before rendering. A variety of 
approximation techniques is available, including uniform and regular parametric, edge length, 
distance, angle, and combined methods. All versions of mental ray support a large range of 
methods: 


e The uniform parametric technique (referred to in the input file as parametric) subdivides 
the surface at equal intervals in parameter space. The input file specifies a factor which is 
multiplied by the surface degree to obtain the number of subdivisions in each parametric 
direction per patch. 


e The regular parametric technique (regular parametric in the input file) is a simpler 
variant of the previous technique. It subdivides the surface at equal intervals in parameter 
space. The number of subdivisions per surface is directly specified in the input file. 


e The edge length technique (using the length keyword) subdivides the surface at equal 
intervals in camera space (in the mi1 format) or in object space (in the mi2 format) — or, 
rather, the intervals will never exceed the given upper bound. Optionally, this bound may 
be specified in raster space (in units of pixel diagonals) rather than camera or object space. 
If, for example, one wanted to approximate a surface with sub-pixel size triangles, one 
could use the edge length approximation technique with a raster space accuracy of 0.5 pixel 
diagonals. 


e The distance-dependent technique (using the distance keyword) subdivides a surface until 
an upper bound on the maximum distance in the space the object is defined in between 
the actual surface and its triangle approximation (known as the distance tolerance). Length 
and distance criteria are scale dependent: the size of the object determines the number of 
triangles, larger objects require more triangles to meet the same length or distance criterion 
because the length and distance scales with the object. Note that the distance criterion will 
not resolve features whose scale is below the given tolerance. The distance criterion may be 
optionally given in raster space, again in units of pixel diagonals. 


* Although the user-settable degree is currently limited to 21, mental ray has no inherent limit. 
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e The angle-dependent technique (using the angle keyword) subdivides a surface until an 
upper bound on the maximum angle (in degrees) between any two normals on a subdivided 
portion of the surface (known as the angle tolerance) is met. In spite of the apparent 
advantage of the size-independent angle criterion over the distance criterion, the angle 
criterion has the undesirable property of resolving small discontinuities ad infinitum, 
whereas the distance criterion will not resolve features whose scale is below the given 
tolerance. Either criterion can be disabled by setting the corresponding tolerance to zero. 


In addition, mental ray 3.1 and later support a new method called fine approximation that is much 
easier to control and works very well with high-detail displacement maps. The view-dependent 
fine length method is now recommended for all high-detail tessellations; regular parametric can be 
used for low-detail objects or the base surface of finely displaced objects. This greatly simplifies 
the choice of methods and parameters. 


e Fine approximation’! can be combined with the length and partly with parametric 


techniques to create a very fine microtriangle approximation that works especially well 
for very detailed displacement maps, resolving every little detail instead of introducing 
tessellation artifacts such as broken edges at contrast boundaries in the displacement map. 
Due to mental ray 3.1’s cache manager, fine approximation does not result in excessive 
memory usage (as non-fine approximation with the same approximation parameters 
would). See page 166 for details. Fine approximation cannot be used together with merging 
and connections. 


The length, distance, and angle criteria can be combined; in this case refinement continues until 
all criteria are met. The any keyword changes this so that refinement stops when amy criterion 1s 
met; this is useful to stop the angle criterion from adding more triangles when the triangle edges 
become smaller than the limit specified by the length criterion, for example. 


View-dependent subdivision, enabled by the view keyword, changes the length and distance 
criteria to work in raster space, interpreting the parameters in pixels instead of 3D units. 
Effectively, closer objects are tessellated more finely. This means that objects that are instanced 
more than once must be triangulated in multiple ways. A tradeoff between the additional memory 
required to store multiple objects and the reduced total number of instanced triangles must be 
evaluated to achieve optimal speed. 


The length, distance, and angle approximation techniques use a recursive subdivision process 
that can also be controlled by two additional parameters, specifying the minimum and maximum 
number of recursion levels. The subdivision can be forced to proceed at least as far as the given 
minimum level, and refinement can be halted at the maximum level. 


All subdivisions of a free-form surface apart from the regular parametric technique and the 
Delaunay technique begin at the patch level. (A patch is the smallest unit of a surface.) If, for 
example, a plane is modeled with ten by ten patches it will be approximated by at least two 
hundred triangles, although two triangles might be adequate. If mental ray seems to be producing 
a large number of triangles in spite of a low approximation accuracy, this is often due to the 
selected patch subdivision algorithm. 
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Free-form curves (trimming curves) may also be approximated by any of the above described 
methods using a technique and tolerances which are distinct from those of the surface which 
the curve trims. The definitions are essentially the same if one considers a curve segment to 
correspond to a surface patch. 


1.3 Edge Merging 


Surfaces are generally approximated independently of each other and small cracks may be visible 
between them, especially if the approximation is coarse. It may be desirable to use a smaller 
tolerance for the trimming curves than for the surfaces themselves. If an object is well-modeled, 
if surfaces meet smoothly along their trimming curves and if the curves are approximated to a 
high accuracy, the gaps between surfaces become invisible. The ideal solution, however, is to 
triangulate surfaces consistently along shared edges. 


mental ray provides the connect construct for specifying connectivity between surfaces. The two 
surfaces are named, along with the two trimming curves and the parameter ranges along which 
they meet. Along such a connection the surfaces will be triangulated consistently resulting in a 
seamless join. 


1.4. Special Points and Curves 


Special points and curves force the triangulation of a free-form surface to include specific 
features. A special point is given in the parameter space of the surface and will be included 
as a corresponding vertex in the triangulation. A special curve is similar to a trimming curve 
but does not cause portions of the surface to be trimmed. Rather, the curve is included as a 
polyline in the triangulation of the surface. Special curves are useful for introducing flexibility in 
the triangulation along specific features. For example, if letters were to be embossed on a planar 
surface using displacement mapping, a series of contour curves around the letters could be created 
with special curves. 


1.5 Hierarchical Subdivision Surfaces 


Hierarchical subdivision surfaces are supported by mental ray versions prior to 3.2 when the 
mental matter library /ibmisubdiv.so is linked in. This library implements the Loop subdivision 
scheme for triangle meshes, and the Catmull-Clark subdivision scheme for quadrilateral meshes. 
The following features are available with this library: 


e C/C++ API for subdivision surface construction and manipulation. This API can be used 
by geometry shaders to create renderable subdivision surface objects. 


e Smooth, dart, conic, cusp and corner vertex features. 


e Crease edges with fractional sharpness. 
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Adaptive local refinement and tessellation, visibility culling. 
e Texturing with unlimited number of texture spaces, motion blur. 


e Trim regions by trim edge specification. 


Multiresolution editing with wavelet decomposition and variable data-dependent smooth- 
ing. 


Export of subdivision surfaces to NURBS. 


mental ray 3.2 and later have subdivision surface rendering (but not modeling) support built 
in, and require no external library. Also, mental ray 3.2 performs displacement mapping during 
computation of the limit surface, using a single approximation setting for the entire tessellation. 


1.6 Atmospheres and Volumes 


The medium which surrounds all objects in a scene is known as the atmosphere. This is normally 
a transparent material with a refractive index of 1.0. A procedural atmosphere can be specified 
by naming a volume shader that determines the attenuation of light as it travels along a ray of a 
given length through the atmosphere. As with all other types of shaders, a user-written shader 
can be used in place of the standard volume shader. This capability can be used, for example, to 
create procedurally defined fog. 


1.7. Materials 


A material determines the response of a surface to illumination. Materials in mental ray consist of 
a material name and one mandatory and seven optional shaders, each of which can be a standard 


shader or a user-provided C/C++ shader: 


e The first shader is the material shader itself. This is the only one that may not be omitted. The 
material shader determines the color of a point on an object, based on its parameters which 
may include object colors, textures, lists of light sources, and other arbitrary parameters. 


e An optional volume shader controls rays passing through the inside of the object. This 
is functionally equivalent to atmosphere calculations, but takes place inside objects, not 
outside. 


e An optional photon shader determines how the material interacts with indirect illumination 
if caustics or global illumination are enabled, much like the main material shader determines 
how the material interacts with direct illumination. 


e An optional photon volume shader determines how the inside of the object interacts with 
indirect illumination if caustics or global illumination are enabled, much like the volume 
shader determines how the volume interacts with direct illumination. 
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e An optional environment shader provides an environment map for non-raytraced 
reflections. 


e An optional displacement shader can be named that displaces a free-form surface at each 
point in the direction of the local surface normal. Displacement maps affect the triangles 
resulting from the tessellation of free-form surfaces, polygonal meshes, and subdivision 
surfaces. 


e An optional shadow shader determines the way shadow rays pass through the object. This 
can be used for calculating colored shadows. 


e An optional contour shader specifies how contours should be drawn in and around the 
object that this material is applied to, if contour rendering is enabled. 


e An optional lightmap shader? causes the object to be sampled to create a light map, which 
collects arbitrary information (usually illumination) about an object that can later be used 
during rendering. 


The shading function may be either a user written function linked at run time, or it may be one 
of the standard functions. Shaders may define parameters that control their behavior. Shaders are 
completely free to define any set of parameters required for their function, but there 1s a set of 
commonly used terms and parameter names that will be found in many parameter lists. 


Parameters have names and values. The declaration of a shader, which is provided by the author 
of the shader, defines the list of possible parameters, including names and types (such as “color” 
or “vector”). The definition of a shader is done in a scene file, and provides the values. For 
example, a shader might have a color parameter named "diffuse" with the value 1.0 1.0 0.0, 
which specifies a yellow color. Parameter values can be given in any order. Parameters can also 
be omitted; mental ray will substitute null values. Shaders are typically programmed to provide 
reasonable defaults in this case. 


1.8 Light Sources 


A light source illuminates the objects in a scene. Light sources in mental ray are programmable 
and consist of a light source name, a named light shader function, and an optional origin and 
direction (exactly one of the two must be present), plus various light-specific parameters such as 
shadowmap and photon information. Light shaders accept shader parameters that depend on the 


shader. 


The lights available in a scene are defined outside materials and typically referenced by name inside 
materials. Most material shaders have a parameter of type “light array” that allows referencing a 
list of light instances by name. The material shader then applies the illumination from these lights 
to the shaded surface. Material shaders also have the option of obtaining a list of all lights in the 
scene directly from mental ray. 


The shading function for light sources may be either a user written function linked at run time, 
or it may be one of the standard functions. There are standard shader libraries for Alias Maya, 
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Autodesk 3ds max, Dassault Systemes CATIA, SOFTIMAGE XSI, SolidWorks, and Wavefront 
compatibility, as well as generic shader libraries such as mental images’ base, physics, and Lume 
shader libraries. 


Some shaders accept a boolean parameter shadow that turns shadow casting on or off for that 
light source, and a floating point factor that is the shadow factor. The shadow factor controls 
penetration of opaque objects. The computation of shadows is a responsibility of light shaders in 
mental ray; in order to compute transparent shadows this may involve the cooperation of shadow 
shaders attached to semi-transparent shadow-casting objects. 


For example, the mib_light_spot shader in the base shader library implements a spot light. It has 
a color parameter that must be set to the color of the light, as three scalars for the red, green, and 
blue components. It also allows a boolean shadow parameter that enables shadows cast from this 
light if its value is on, and a factor parameter that controls shadow penetration, ranging from 
0.0 for black shadows to 1.0 for invisible shadows. The shader also accepts a boolean atten 
parameter that turns distance attenuation on or off, and two scalar parameters start and stop 
that specity the range over which the attenuation falls off if atten is on. The spot light mode 
requires an origin, a direction, and a spread value in the light definition in the scene description 
file. The spread value in the light definition and the cone parameter of the shader together define 
the spot characteristics of the light. The cone parameter specifies the angle of the inner solid cone 
and the spread statement specifies the outer falloff cone. The spot casts a cone of light with a 
softened edge where the intensity falls off to zero between the cone and spread angles. This and 
most other shaders specify angles not in degrees but in the cosine of one-half of the opening angle 
to improve performance: 1.0 is an opening angle of 0 degrees (a laser beam too narrow to see), 
0.707 specifies an opening angle of approximately 90 degrees (because cos 92 ~ 0.707) and 0.0 
specifies an opening angle of 180 degrees. 


1.9 Area Light Sources 


The main purpose of area light sources is to generate more realistic lighting, resulting in soft 
shadows. This is achieved by using one of six primitives (rectangles, discs, spheres, cylinders, 
user?'', or geometric objects?!) as light sources with nonzero area. This means that a point on an 
object may be illuminated by only a part of a light source, which creates accurate soft shadows. 


Area light sources are based on similar principles as motion blurring. 


Area light sources are specified in the .mi file by naming a primitive in a standard light definition. 
Any of the standard spot and point lights can be turned into an area light source. Infinite light 
sources ignore any area specifications because the size of a light at infinite distance does not 
matter, by definition. 


There are four different shapes of area light sources: rectangles, flat discs, spheres, and cylinders. 
mental ray 3.1 adds arbitrary geometric objects, and a user-defined shape. The orientation of 
the disc and rectangle shape may be chosen independently of the light direction of spot and 
directional light sources. Any type of light shader can be used. 
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1.10 JES and Eulumdat Light Profiles>: 


mental ray 3.1 and higher support IES and Eulumdat light profiles. Light profiles are made 
available by vendors of physical lamps to describe precisely how much light is emitted in which 
direction. Light profiles are generated by measuring emitted light at the grid points of a grid 
placed around the light. For any light direction, this allows determining the light energy by 
interpolating the nearest grid points. Eulumdat is a European format while IES is an international 
standard. 


mental ray can parse IES and Eulumdat light profiles when used and store them as an approximated 
erid for efficient lookups. Light profiles are a new shader parameter type that a shader can access 
like any other parameter. New shader interface functions allow the shader to extract the brightness 
for a given direction from the profile parameter. 


Light profiles assume that the light is an exact point light, and guarantee only that the 
IES/Eulumdat computation is correct at a sufficient distance. However, mental ray also allows 
assigning standard area light source definitions to the light source in order to give a credible 
approximation at close distances, such as soft shadows which are not achievable with light 
profiles alone. 


1.11 Shadow Maps 


Shadow mapping is a technique that generates fast approximate shadows. It can be used for fast 
previewing of models or as an alternative to the more accurate (but also more costly) ray marching 
based approach in scenes where accurate shadows are not required. Shadow maps are particularly 
efficient when a scene is rendered several times without changes in the shadows (for example an 
animation where some of the lights and shadow-casting objects are not moving). 


A shadow map 1s a fast depth buffer rendering of the model as seen froma light source. This means 
that each pixel in a shadow map contains information about the distance to the nearest object in 
the model ina particular direction from the light source. This information can be used to compute 
shadows without using shadow rays to test for occluding objects. The shadow computation is 
based only on the depth information available in the shadow maps. For fast previewing of scenes, 
shadow maps can be used in combination with scanline rendering to produce fast approximate 
renderings with shadows — without using any ray marching. 


Two different kinds of shadows can be produced with shadow maps: sharp and soft (blurry) 
shadows. Sharp shadows are very fast, and depending on the resolution of the shadow map they 
will approximate the result produced with simple ray marching. Soft shadows are produced by 
distributing one or more samples in a region of the shadow map. This technique produces soft 
shadows everywhere and is not as accurate as the ray marching based approach for computing 
soft shadows but is much faster. 


Shadowmaps normally store the halfway point between the first two shadow intersections, which 
is called the “Woo trick”. If there is no second hit, 0 (infinity) is stored because no shadow can 
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exist, since there is no second object that the shadow could be cast onto. However, the second 
hit can come from a previous render whose shadowmap we are merging, so 0 (infinite) depths 
can occur in both the old and the new shadowmap because both saw only one hit, but together 
that’s two hits and there should have been a nonzero depth. Hence, shadowmap merging is 
fundamentally incompatible with the Woo algorithm. 


mental ray 3.3 implements a new shadowmap algorithm based on explicit shadowmap bias values. 
The bias is a world-space distance stored in the options block and light source definitions. Lights 
override the options; the options apply to all lights that do not have their own bias. A bias of 
zero means “no bias”; a light that gets a non-zero bias uses the bias algorithm while all others 
use the Woo algorithm. Bias values should be chosen smaller than the smallest distance between 
a shadow caster and a shadow receiver, but not too small to avoid shadow acne due to numerical 
inaccuracy. The bias algorithm stores the depth of the first intersection directly, after adding the 
bias value, without looking for a second intersection. 


Shadowmaps saved to files store the bias value, and the actual depths from the light with no bias 
applied. The bias is applied during lookup, not during storage. When the shadowmap file is later 
loaded from disk, the bias of the new scene and not the one stored in the shadowmap will be 
used. As an exception, if the shadowmap file contains a bias but the new frame does not (because 
it uses the midpoint Woo algorithm), the old file is adjusted by its bias on loading. This allows 
merging biased and Woo maps, but it is not recommended. 


To set a bias in a light or the options in the scene file, use the statement shadowmap bias N. The 
options bias can also be set with the command-line argument -shadowmap_bias N. 


Standard shadow maps always assume that shadow-casting objects are fully opaque, and never 
call shadow shaders. mental ray 3.3 and higher also support detail shadowmaps that collect more 
information about shadow-casting objects. They have features that are a combination of standard 
shadow maps and raytraced shadows. In most aspects they behave like standard shadow maps, 
but they also call shadow shaders if present. Since shadow shaders return transparencies, detail 
shadowmaps do not store a simple depth value, but a list of depth values together with the 
light transmission coefficients at each depth. Detail shadowmaps are more expensive to calculate 
than standard shadow maps, since they may invoke shadow shaders. They typically store more 
information per pixel than standard shadow maps. 


1.12 Texture Mapping and Texture Files 


mental ray supports texture, bump, displacement and reflection mapping, all of which may be 
derived from an image file or procedurally defined using user-supplied shaders. Although there 
are various support functions provided by the mental ray shader interface, all these functions are 
fully implementable in shaders. 


Procedural textures are computed by shaders, while image textures are read from image files. In 
practice, textures are a combination of both methods: a procedural texture shaders accepts an 
image texture parameter, which it accesses to read and filter pixels, and then modifies it according 
to other parameters to implement projections, scaling, cropping, replication, and other common 
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operations on texture images. Purely procedural texture shaders that do not rely on texture 
images at all also exist, for example marble or cloud shaders. Some shaders use textures for special 
purposes; for example, a fur shader that computes hair in a volume might use a texture image to 
control the hair length or brushing direction. 


The following table lists the file formats accepted by mental ray for reading texture image files: 


colormap compress comp. _bits/comp. 


Wavetront image 

Softimage image 

Alias image 
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JFIF image 

Portable Network Graphics? ? 
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mental images depth channel 
mental images vectors 
mental images tag channel 
mental images bit mask 
memory mapped textures 
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In the table, any combination of comma separated values determines a valid format subtype. For 
example, the SGI RGB image format will be read when the data type is 8 bits per component 
with or without alpha, either RLE compressed or uncompressed. The actual image format is 
determined by analyzing the file content, not just by checking the filename extension. This 
allows replacing texture files with memory-mapped textures without changing the name, for 
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example. The asterisk (*) indicates omission; for example, ct* includes cttp (floating point), cth 
(HDR), and ct16 (16 bits). 


Typical image types like black/white, grayscale, colormapped and truecolor images, optionally 
compressed, are supported. Some of them could be used to supply additional alpha channel 
information (number of components greater than 3). The collection covers most common 
platform independent formats like TIFF and JFIF/JPEG’, OpenEXR’, special UNIX (PPM) or 
Windows bitmap (BMP) types and well known application formats. The mental images formats, 
normally created by mental ray itself, are mainly available to exchange data not storable with 
other formats. As a special case, mental ray allows storing RGBE>"' data into file formats that 
accept RGBA. As a special case, mental ray 3.2 allows the iff format to store both a color and 
depth image in the same file, if a type list "+rgba,z" is specified. 


A user-defined material shader is not restricted to the above applications for textures. It is free 
to evaluate any texture and any number of textures for a given point, and use the result for any 
purpose. 


In the parameter list of the standard material shaders, a list of texture maps may be given in 
addition to, for example, a literal RGB value for the diffuse color component of a material. 
The color of the diffuse component will then vary across a surface. To shade a given point on 
a surface, the coordinates in texture space are first determined for the point. The diffuse color 
used for shading calculations is then the value of the texture map at these coordinates. The 
SOFTIMAGE-compatible material shader uses a different approach; it accepts a single list of 
textures, with parameters attached to each texture that control the way the texture is applied to 
ambient, diffuse, and other parameters. The shader interface is extremely flexible and permits 
user-defined shaders to use either of these approaches, or completely different formats. The 
remainder of this section describes the standard shader parameters only. 


The standard material shaders support texture mapping for all standard material parameters 
except the index of refraction. Shinyness, transparency, refraction transparency, and reflectivity 
are scalar values and may be mapped by a scalar map. Most shaders use color maps to implement 
bump mapping by sampling the color map three times, but some shaders such as the Wavefront 
material shader accept a vector map that requires only a single sample. 


Color textures are normally not implemented in the material shader but in a separate texture 
shader, which is then referenced by the material shader. This separation of work between material 
and texture shaders allow more flexibility because any texture shader to be combined with any 
material shader, without having to program any new combination in a new material shader. Also, 
texturing does not have to be programmed into every material shader parameter. Instead, the 
material shader offers simple parameters like “diffuse”, “ambient”, “transparency”, “shinyness”, 
and so on. Each parameter may be assigned a static color such as “white”, or it may be attached 
to a texture shader. Even if the material shader was never programmed to accept textures, all 
aspects of its operation for which it has a parameter become texturable. In fact it is possible to 


build whole multilevel graphs of shaders using parameter assignment. 
>The JPEG software is based in part on the work of the Independent JPEG Group. 


*OpenEXR is available only on Linux, Irix, MacOS X, and Intel-Windows. It is not available on Visual C++ Windows. 
OpenEXR is very picky about where it works. Integration source code is available on request for custom integration. 
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Shaders that do all the work internally are called monolithic shaders, while shaders designed for 
easy graph building are called base shaders. 


Determining the texture coordinates of a point on a surface to be shaded requires defining a 
mapping from points on the surface to points in texture space. Such a mapping is itself referred 
to as a texture space for the surface. Multiple texture spaces may be specified for a surface. If the 
geometry is a polygon or subdivision surface, a texture space is created by associating texture 
vertices with the geometric vertices. If the geometry is a free-form surface, a texture space is 
created by associating a texture surface with the surface. A texture surface is a free-form surface 
which defines the mapping from the natural surface parameter space to texture space. Texture 
maps, and therefore texture spaces and texture vertices, may be one, two, or three dimensional. 


Pyramid textures are a variant of mip-map textures. When loading a texture that is flagged with 
the filter keyword, mental ray builds a hierarchy of different-resolution texture images that 
allow elliptical filtering of texture samples. (The .map format may already contain this pyramid, 
which saves a lot of time and memory.) Without filtering, distant textures would be point-sampled 
at widely separated locations, missing the texture areas between the samples, which causes texture 
aliasing. Texture filtering attempts to project the screen pixel on the texture, which results in an 
elliptic area on the texture. Pyramid textures allow sampling this ellipse very efficiently, taking 
every pixel in the texture in the ellipse into account without sampling every pixel. Pyramid 
textures are not restricted to square and power-of-two resolutions, and work with any RGB or 
RGBA picture file format. The shader can either rely on mental ray’s texture projection or specify 
its own. Filter blurriness can be adjusted per texture. 


A procedural texture is free to use the texture space in any way it wants, but texture files are always 
defined to have unit size and to be repeated through all of texture space. That is, the lower-left 
corner of the file maps to (0.0, 0.0) in texture space, and again to (1.0, 0.0), (2.0, 0.0), and so on; 
the lower-right corner maps to (1.0, 0.0), (2.0, 0.0), etc. and the upper right to (1.0, 1.0), (2.0, 2.0), 
etc. 


1.13, Memory-Mapped Textures 


mental ray supports memory mapping of textures on UNIX and NT. Memory mapping means 
that the texture is not loaded into memory, but is accessed directly from disk when a shader 
accesses it. There is no special keyword or option for this; if a texture is memory-mappable, 
mental ray will recognize it and memory-map it automatically. Only the map image file format 
(standard extension .map, but mappable files are recognized even if they have an extension other 
than .map) can be mapped. See the Output Shaders chapter for a list of supported file formats. 


mental ray 3.2 uses an additional texture cache to optimize access to mappable texture caches, and 
uses OS memory mapping only where it improves performance. This greatly improves memory 
and virtual address space usage, and is fully automatic. 


Note that memory mapping is based on the concept that the image data on disk does not 
require decoding or data type conversion, but is available in the exact format that mental ray 
uses internally during rendering. Normally mental ray will attempt to auto-convert image data 
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formats; for example if a color image file is given in a scalar texture construct, mental ray 
will silently convert the color pixels to scalars as the texture is read in. Most data types are auto- 
converted to most other data types. This does not work for memory-mapped textures because it 
would defeat the purpose. This also applies to the byte order. 


Memory mapping requires several preparation steps: 


e The texture must be converted to .map format using a utility like mental images’ imf_copy. 
The scene file must be changed to reference this texture. Note that mental ray recognizes 
-map textures even if they have an extension other than .map; this can be exploited by 
continuing to use the old file name with the “wrong” extension, to avoid having to change 
the scene file. When using imf_copy, the -p option is highly recommended to create a 
texture pyramid in the file. 


e Memory-mapped textures are automatically considered local by mental ray 2.1, as if the 
local keyword had been used in the scene file. This means that if the scene is rendered on 
multiple hosts, each will try to access the given path instead of transferring the texture across 
the network, which would defeat memory mapping. The given path must be valid on every 
host participating in the render. mental ray 3.x also supports nonlocal mapped textures, 
so that it is mapped on the master but fetched across the network by slaves if the local 
keyword is not supplied, which simplifies scene distribution but may incur unacceptable 
network overheads. 


e The texture should not be on an NFS-mounted file system (one that is imported across 
the network from another host). Although this simplifies the requirement that the texture 
must exist on all hosts, the necessary network transfers reduce the effectiveness and can 
easily make memory-mapping slower than regular textures. 


e Memory-mapping works best if there are extremely large textures containing many tens of 
megabytes that are sampled infrequently because then most of the large texture file is never 
loaded into memory. 


e A memory-mapped file texture must be created on a host with the same byte order as the 
host where it will be used. mental ray will not memory-map textures with an incompatible 
byte order, and read the whole texture into memory and convert it instead. This is not 


efficient and should be avoided. 


If the textures and the scene are so large that they do not fit into physical memory, loading a 
texture is equivalent to loading the file into memory, decompressing it, and copying it out to 
swap. (The swap is a disk partition that acts as a low-speed extension of the physical memory 
that exists as RAM chips in the computer.) From then on, accessing a texture means accessing 
the swap. Memory mapping eliminates the read-decompress-write step and accesses the texture 
from the file system instead of from swap. This has the side effect that less swap space is needed. 
If the texture and scene are not large and fit into memory, and if the texture is accessed frequently, 
memory-mapped textures are slightly slower than regular textures because the swap would not 
have been used, but for textures that are larger than perhaps a hundred kilobytes (uncompressed), 
memory mapping is a much more efficient way of loading textures. 
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This is especially important for mental ray 3.x, which manages memory as a cache. Non-memory 
mapped textures are a big drain on the cache because they tend to take up large portions of cache 
memory. mental ray 3.x has a separate virtual cache manager that loads and unloads memory- 
mapped textures efficiently without blocking the regular cache. 


1.14 Bump, Displacement, and Reflection Mapping 


Just as a texture map can vary a parameter such as the diffuse color over every point on a surface, 
a bump map can be associated with a material, perturbing the normal at every point on a surface 
which uses the material, simply by applying an appropriate shader. This will affect the shading, 
though not the geometry, giving the illusion of a pattern being embossed on the surface. 


Bump maps, like texture maps, require a texture space. In addition, bump maps require a pair 
of basis vectors to define the coordinate system in which the normal is displaced. A bump map 
defines a scalar x and a scalar y displacement over the texture space. These components are used 
together with the respective basis vectors in order to calculate a perturbed surface normal. The 
basis vectors can be automatically defined for free-form surfaces in a way which conforms to the 
texture space; for polygons and subdivision surfaces, the basis vectors must be explicitly given 
along with the texture coordinates for every polygon vertex. However, most commonly basis 
vectors are computed procedurally by shaders during rendering. 


A displacement map is a scalar map which is used to displace a free-form surface, polygon, or 
subdivision surface at each point in the direction of the local normal. Like texture, bump and 
reflection maps, displacement maps are controlled by shaders that are used by mental ray to 
determine the displacement of points on the surface, in order to decide how to deform the surface 
and introduce geometric detail. 


The surface must be triangulated finely enough to reveal the details of the displacement map. In 
general, the triangles must be smaller than the smallest feature of the displacement map which is 
to be resolved. 


Displacement mapped polygons are at first triangulated as ordinary polygons. The initial 
triangulation i is then further subdivided according to the specified approximation criteria. The 
parametric technique subdivides each triangle a given number of times. All the other techniques 
take the displacement into account. The length criterion, for example, limits the size of the edges 
of the triangles of the displaced polygons and ensures that at least all features of this size are 
resolved. As the displaced surface is not known analytically, the distance criterion compares the 
displacements of the vertices of a triangle with each other. The criterion is fulfilled only if they 
differ by less than the given threshold. Subdivision is finest in areas where the displacement 
changes. The angle criterion limits the angle under which two triangles meet in an edge contained 
in the triangulation. Subdivision stops as soon as the given criterion or combination of them is 
satisfied or the maximum subdivision level is reached. This does not preclude the possibility that 
at an even finer scale new details may show up which would again violate the approximation 
criteria. 


mental ray 3.2 and higher support rendering subdivision surfaces as a builtin geometry type, 
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and handles displacement mapping on subdivision surface as part of the tessellation to the limit 
surface. Versions prior to 3.2 required installing a separate mental matter library, and handled 
displacement in a separate stage by treating the triangles of the finished limit surface as a polygon 
mesh to be displaced. 


For displacement mapped free-form surfaces approximation techniques can be specified either 
on the underlying geometric surface or for the surface resulting from the displacement. Before 
mental ray version 2.0, only the former method existed. This is still available, but it does not take 
into account variations in curvature imparted to the surface as a result of displacement mapping. If 
one wants to control the approximation from the geometric surface, the most suitable technique 
for use with displacement mapping on free-from surfaces is usually the view dependent uniform 
spatial subdivision technique, which allows specification of triangle size in raster space. 


In addition to or even instead of specifying the subdivision criteria for the base surface, they can 
be given for the displaced surface itself. This approximation statement works exactly the same 
way as for polygons, i.e. an initial tessellation is subdivided until the criteria on the displaced 
surface are met. 


The final type of map is an environment map. This is a color-mapped virtual sphere of usually 
infinite radius which surrounds any object referencing the given material. This sphere 1s also seen 
by refracted rays; the environment seen by first-generation (primary) rays can also be specified 
but is part of the camera, not of any particular material. In general, if a ray does not intersect any 
objects, or if casting such a ray would exceed the trace depth, the ray is considered to strike the 
sphere of the environment map of the last material visited, or the camera environment map in 
the case of first-generation rays that did not hit any material. An environment shader is used to 
determine the color of each point of the sphere. 


The environment map always covers the entire sphere exactly once. Rotations, translations, and 
repetitions are supported by special shader parameters or remapping shader nodes such as the 
ones found in the base shader library. There are also environment shaders that implement cubical 
instead of spherical environment maps, and cubical maps of finite instead of infinite size. 


As described before, textures can be used for any purpose whatever to control shader behavior, 
in addition to the examples in this section. 


1.15 Texture Filtering 


mental ray provides two methods for texture filtering: a fast filtered texture lookup using image 
pyramids (which are similar to mip-map textures but have no restrictions on texture size), and 
a high-quality filtering method using elliptical projections. Both methods operate on image 
pyramids. There is a .map image format defined by mental ray that supports filters. 


When standard image files (such as . rgb) are used for filtered texture lookups (both methods), the 
pyramid must be created by mental ray when the image is accessed. For high-resolution images 
this can take a long time (sometimes up to a minute), so it is highly recommended to create this 
image pyramid “offline” by mental images’ imf_copy utility. When called with the -p option on 
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the command line, it down-filters the source texture image file and writes out the filtered images 
in memory-mapped image format. If such a file is read with a local filter color texture 
statement in .mi scene file, the pyramid is read almost instantaneously. 


Also, it is recommended to make local copies of the texture files on the machines in order to 
speed up access. When machines with different byte order are used in the network, there is a 
performance penalty when using only one version of the pyramid .map file (it has to be byte 
swapped), so it is necessary to generate the .map file in the native byte order on the respective 
machines. 


The prefiltered .map file containing the pyramid can also be used for standard nonfiltered texture 
lookups (using a simple local color texture statement), in this case only the first (finest) level 
of the image pyramid is used. 


Now the two methods in detail. 


1.15.1 Pyramid Filtering 


This method can be used very easily with existing .mi files, it is only necessary to add a “filter 
scale” modifier to the texture load statements in the scene file. Here is an example: 


local filter 0.8 color texture "tex_0" "mytexture.map" 


The basic idea behind pyramid filtering is that when a pixel rectangle (the current sampling 
location) is projected into texture space, mental ray has to calculate the (weighted) average of 
all texture pixels (texels) inside this area and return it for the texture lookup. Using the average 
of the pixels, high frequencies which cause aliasing are eliminated. To speed up this averaging, 
the compression value is calculated for the current pixel location which is the inverse size of the 
pixel in texture space. For example, if the pixel has a projected size of four texels in texture space, 
then one texel is compressed to 1/4 in the focal plane (severe compression gives those aliasing 
artifacts). 


It is very costly to project a rectangle to texture space, so usually the quadrilateral in texture space 
is approximated by a square and the length of one side is used for the compression value. The 
compression value is used as an index into the image pyramid, and since this value has a fractional 
part, the two levels that the value falls in between are looked up using bilinear interpolation at 
each level, followed by a linear interpolation of the two colors from the level lookups. (mental 
ray uses also bilinear texture interpolation when no filtering is applied). 


Just specifying “filter scale color texture” is not sufficient for an exact projection of the pixel 
to texture space. The texture shader modifies the UV texture coordinates (either from specified 
texture surfaces or generated by cylinder projections) according to remapping shader parameters 
etc. the standard shader interface function mi_lookup_color_texture provides only the UV texture 
coordinates to mental ray, and it is almost impossible to project the pixel corners to texture space 
since it is not known how to obtain additional UV coordinates or how to remap them. The 
remapping 1s done before mi_lookup-_color_texture is called. 
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mental ray’s implementation of pyramid mapping therefore adds a vector to the current 
intersection point in object space and transforms this point into raster space. The length of 
the offset vector is calculated by dividing the object extent by the texture resolution (the larger 
value of width and height is used). This approach assumes that texture space corresponds to 
object space (that is, if the object size is one object unit, the texture fully covers it). If a texture 
shader applies texture replications, the filter value should be set to the replication count or larger 
to adjust for this effect. The compression value is calculated as the distance between the raster 
position mentioned above and the current raster position (using two variables provided to the 
shader, state — raster_x and state — raster_y). 


Since this can not always attain satisfying results, mental ray allows multiplication of a “user 
scaling” value — the scale value in the filter statement. Using this value, it is possible to reduce 
blurring (scale < 1) or increase blurring (scale > 1). For example, if the texture is replicated 10 
times, which makes it appear smaller in raster space and hence requires more blurring, the filter 
constant should be multiplied by 10. Since texture projections are handled by shaders and not by 
the mental ray core, this cannot be done automatically. 


Pyramid filtering also works when reflection or refraction is used, but mathematical correctness 
cannot be guaranteed since mental ray cannot take reflection or refraction paths into account, for 
the same reason. 


1.15.2 Elliptical Projection Filter Lookup 


This method was implemented in mental ray in order to provide a very high quality texture 
filtering, far superior to the pyramid filtering explained above. It eliminates most if not all 
of the aliasing in high texture frequencies. When using checkerboard textures mapped onto a 
rectangle, for example, there is much less blurring at the horizon where the texture compression 
is severe. With mip-map textures as explained above, the blurring at such extreme compressions 
is sometimes still visible. 


The main cause for the excessively blurry-looking images using mip-maps is the approximation of 
the pixel projection area by a square. With elliptical filtering a circle around the current sampling 
location is projected to texture space and will give either a circle or an ellipse as a projection 
shape. Instead of approximating this curve by simple shapes like squares, a direct convolution 
(averaging) of all texels which are inside the ellipse area is done. Averaging all texels in this area 
can take quite long, so mental ray uses pyramids of prefiltered textures to accelerate this. There 
are various parameters explained below which control modification of ellipse shape and level 
selection in the pyramid. | 


The most difficult part when elliptical projections are used is that a screen to texture space 
transformation matrix has to be provided. This matrix is used in the filtering code to transform 
the circle around the current sampling location to texture space. mental ray provides two helper 
functions for constructing this matrix when UV texture coordinates are available; see mi_texture-_ 
filter project in the Writing Shaders chapter. If those are not available and (for example) direct 
cylinder projective mappings are used, it is much easier to calculate this matrix. 


The following filtering algorithm is applied: first, a circle in the current sampling location is 
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transformed to the ellipse using the provided transformation matrix. Then the eccentricity of the 
ellipse is calculated (major radius divided by minor radius). If the eccentricity is larger than a 
specified maximum, the minor radius is adjusted (made larger) to make sure that this eccentricity 
maximum always holds. The reason for this enlargement is that the direct convolution is done in 
the pyramid level based on the minor axis length of the ellipse. There is another parameter which 
specifies the maximum allowed number of texels the minor radius may cover. If that number is 
exceeded in the finest level (zero), a higher level is used. In the second level, for example, the 
minor radius has half the size etc. Enlarging the minor radius when the eccentricity is exceeded, 
basically means that we are going up in the pyramid. So, for very large ellipses, mental ray is 
making them “fatter” and uses a higher level in the pyramid. Referring to the checkerboard- 
mapped plane example above, the circle is projected to very large thin ellipses near the horizon, 
covering thousands of texels, and using the technique above, mental ray just makes a few texture 
lookups in the higher pyramid levels. 


There is another parameter which modifies the size of the circle to be projected, usually the radius 
is 0.5, making it larger introduces more blurring, making it less gives more aliasing. 


The projection helper functions expect another parameter which is the maximum offset of the 
central sampling location to the two other points which have to be selected. The other two points 
should be inside the pixel, but since mental ray is using the current intersection primitive (the 
triangle) also for these points to determine the UV texture coordinates, a smaller value than 0.5 
(pixel corners) is appropriate since mental ray might hit the triangle plane outside the triangle area. 
Usually 0.3 gives good results. When the UV coordinates are calculated using cylinder projections, 
it 1s possible to obtain the UV coordinates much faster and also much more accurately. 


1.16 Light Mapping>« 


Light mapping, also sometimes called texture baking, was introduced with mental ray 3.0. In 
general terms, it is a method for sampling an object before rendering, and storing the results for 
later use. The most common application samples illumination for each point of a texture image 
wrapped around the object, and stores that illumination in the texture. Illumination is effectively 
frozen into the texture, which can later be mapped onto an object in the conventional way. 


The advantage is that rendering can obtain illumination quickly from the frozen illumination, 
instead of computing it at rendering time. This is especially valuable for indirect illumination, 
which takes more time to compute than direct illumination. Such textures, called light maps, are 
also commonly used in games. 


Creating light map textures is fundamentally different from regular textures because the texture 
is written to disk, instead of read from disk. mental ray uses a writable keyword in the scene 
file, and special light mapping functions in the shader interface to gain write access to the texture. 


Light mapping in mental ray is very flexible, and implemented with lightmap shaders. Lightmap 
shaders are initially called once per object triangle vertex (“vertex mode”), and then once more 
for the entire objects (“output mode”). The standard lightmap shader in the base shader library 
uses the per-vertex calls to collect point and normal information, which is then projected onto 
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the texture during the final call, which samples illumination for each pixel of the texture. Other 
shaders could sample the illumination per vertex and use the final call only for color interpolation; 
this may be useful for game development using hardware vertex coloring but would create a very 


low-fidelity light map. 


Light mapping is enabled by attaching a lightmap shader to the material of the object to be 
lightmapped. mental ray always samples the entire object even if the material is applied to only 
some parts of its surface. If the shader requires it, the scene must provide an appropriate texture 
projection. 


1.17 Multipass Rendering: 


Sometimes, very large scenes are not rendered in one pass but in multiple passes, because they 
are too large for the machine, or because different passes are rendered on different machines to 
increase parallelism, or because some passes are expected to change while others stay the same, so 
only the modified passes need to be rerendered. (This last one is very common in entertainment 
content production.) 


It is generally not sufficient to render multiple images and then composite them into one. Pass 
compositing is not simple alpha blending but a complex user-defined process that involves at 
least the Z depth. Although mental ray supports saving the Z buffer to files, there is only one Z 


value per pixel. 


mental ray supports multipass rendering by saving rendering results not as image files but as 
sample files. Every primary ray is a sample, and is stored with all available frame buffer values. In 
the scene contains motion, an averaged result over all temporal samples is stored. The file format 
used for sample files is unpublished and may change with new versions of mental ray, it is not 
useful as a data interchange format for other programs, and is not intended for long-term storage. 
Merging is done by a user-defined function (if absent, a simple Z switcher is used) that has access 
to all frame buffer results of all passes, one sample at a time. Multipass rendering is controlled 
with a pass statement script in the camera definition that is similar to output statements. 


mental ray 3.2 and higher use compression to reduce the size of pass files. Pass files are generally 
backwards-compatible, but not forward-compatible. Also, passes created with and without the 
rasterizer’* (formerly called Rapid Motion) should not be merged because the sampling patterns 
do not agree: passes rendered with the rasterizer are based on sampling of (sub)pixels, whenever 
passes rendered without it are based on sampling of (sub)pixel corners. For this reason, in most 
cases passes rendered without the rasterizer have 1 sample higher resolution per rendered tile. 
mental ray 3.2 can also merge pass files that were created with dissimilar max sampling rates using 
appropriate upsampling or downsampling, although it is recommended to use matching sampling 
densities. Multipass rendering does not work with slave hosts. 
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1.18 User-Defined Shaders 


In addition to standard shaders, user-defined shaders written in standard C or C++ can be 
precompiled and linked at runtime, or can be both compiled and linked at runtime. User- 
defined shaders can be used in place of any standard shader, redefining materials, textures, lights, 
environments, volumes, displacements etc. mental ray’s shader interface uses C conventions, 
C++ shaders should use extern "C" constructs to access it and take care to avoid typical C++ 
performance pitfalls such as new and virtual class members. Even a small overhead becomes 
significant if incurred millions of times per frame. 


mental ray can link in user-defined shaders in either object, source, or dynamic shared object 


(DSO or DLL) form. 


Every user-defined shader must be declared before it can be used. A declaration is a statement 
that names the shader, and lists the name and type of all its parameters. 


Declarations may appear in the .mi scene description file, but are typically stored in an external 
file included at run time. Note that all code and Link statements must precede the first declaration 
in the .mi file. 


Available parameter types are boolean, integer, scalar, string, color (RGBA), vector, transform 
(4 x 4 matrix), scalar texture, color texture, vector texture, shader, material, geometry, and light. 
In addition to these primitive types, compound types may be built using struct and array 
declarations. Structs may be nested but arrays may not. 


An instance of a shader can be created by creating a material, texture, light etc. that names a 
declared shader and associates a parameter list with values. Any parameter name that appeared 
in the declaration can be omitted or listed in any order, followed by a value that depends on the 
parameter type. Omitted parameters default to 0. Scalars accept floating point numbers, vectors 
accept one to three floating point numbers, and textures accept a texture name. 


After a material, texture, light etc has been created, it can be used. Materials are used by giving 
their names in object geometry statements, and textures and lights are used by naming them as 
parameter values in other shaders, typically material shaders. 


When the C function that implements a user-defined shader is called, it receives three pointers: 
one points to the result, one to global state, and one to a data structure that contains the parameter 
values. mental ray stores the parameter values in that data structure using a layout that corresponds 
exactly to the layout a C compiler would create, so that the C function can access parameters 
simply by dereferencing the pointer and accessing the data structure members by name. For this, 
it is necessary that a struct declaration is available in C syntax that corresponds exactly to the 
declaration in .mi syntax. 


For details on user-defined shaders, refer to the “Writing Shaders” chapter. 
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119 The Camera 


The camera is fixed at the origin, looking down the negative Z axis, with up being the positive Y 
axis, in its own coordinate space called “camera space”. The camera can be placed anywhere in 
world space using an instance transformation, in the same way that objects are placed anywhere 
in world space. (For backwards compatibility with mental ray 1.x, there is also a mode where 
camera space and world space are always identical.) 


By default, the camera is a pin-hole perspective camera for which the focal length, aperture and 
aspect ratio may be specified in either the camera construct of the input file or on the command 
line of mental ray. Optionally, lens effects such as depth of field can be achieved by specifying 
one or more lens shaders. 


1.20 Lens Effects 


Lens effects are distortions of the rendered image achieved by changing the light path through the 
camera lens. Because lens effects are applied to first-generation rays, there is no loss of quality that 
would be unavoidable if the distortion were applied in a post-processing stage after rendering. 


Lens effects are introduced by specifying one or more lens shaders in the camera statement. If no 
lens shaders are present, the standard pinhole camera is used. Each lens shader is called with two 
state variables that specify the ray origin and the ray direction. The lens shader calculates a new 
origin and a new direction, and casts an eye ray using the mz_trace_eye function. The first lens 
shader always gets the position of the pinhole camera. All following lens shaders get the origin 
and direction that the previous lens shader used when calling mi_trace_eye. 


Some lens shaders imply ray marching. If lens shaders change the origin or direction of a ray they 
only work correctly if scanline rendering is turned off. This is normally automated and does not 
require the user to modify the scene: lens shader declarations should supply this information to 
inform mental ray that the shader requires ray marching. 


Lens shaders that do not change the origin or direction of a ray are also useful, for example 
to perform color correction or special data collection. Such shaders should not disable scanline 
mode in their declaration. 


1.21. Depth of Field 


Depth of field is an effect that simulates a plane of maximum sharpness, and blurs objects closer 
or more distant than this plane. There are two methods for implementing depth of field: a lens 
shader can be used that takes multiple samples using different paths to reach the same point 
on the focus plane to interpolate the depth effect; or a combination of a volume shader and an 
output shader that collect depth information during rendering and then apply a blurring filter 
as a postprocessing step over the finished image using this depth information. Both methods are 
supported by shaders. 
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1.22 Animation 


Animations are sequences of frames. Since the definition of a scene for a single frame can be quite 
large, and since the differences for successive frames tend to be small, mental ray is based on a 
scene database that remains intact after rendering, and can be edited to get ready for the next 
frame. Such edits are called incremental changes. 


For example, a camera flythrough is an ideal case for incremental changes because only the camera 
position (more precisely, the camera instance) must be changed from one frame to the next, while 
the rest of the scene is unchanged. 


Incremental changes operate on the level of “toplevel elements” of the scene graph: options, 
cameras, objects, light sources, instances, groups, shaders, etc. Most elements can be edited while 
retaining previous values. For example, to turn ray marching off, it is sufficient to incrementally 
change the options element, and only supply the new value of the “trace” attribute, without 
redefining the other attributes. Shaders and geometric objects are always redefined from scratch 
because incremental changes tend to change not just values but the complete structure layout, 
and in the case of objects would require long-term storage of large amounts of source data not 
needed for rendering. 


The database principle also allows storage of several disconnected scenes or parts of scenes. 
Deleting scene elements is also possible, but care should be taken not to manually delete elements 
that are still referenced by other elements. 


1.23 Motion Blur 


mental ray computes motion blur of highlights, textures, shadows, reflections, refractions, 
transparency, and intersecting objects. There are two methods of defining motion blur: 


e instance motion blur defines a transformation matrix that controls the orientation of the 
instanced object, light, or camera after a shutter interval of one time unit, in addition to the 
regular transformation matrix that defines the orientation at the beginning of the shutter 
interval. For cameras, this creates true curved blurs. Moving lights cause blurred highlights 
and shadows. 


e motion vectors can be defined at object vertices to create internal motion caused by shape 
changes. Each vertex has a vector associated with it that describes how far that vertex moves 
in one time unit. For deferred objects (supported by mental ray 3.0 and higher inly), where 
the vertices are created later during rendering, it is necessary to supply a motion bounding 
box that describes the lowest and highest expected motion vector components. Cameras 
and lights do not allow motion vectors because they cannot change shape. mental ray 3.1 
and higher support motion paths with up to 15 motion vectors per vertex. 


Both methods can be combined. mental ray supports motion blur both in scanline and raytracing 
mode. Motion blur does introduce rendering overhead only where blur must be computed; if 
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the camera moves this could be the entire image but if only a small object moves the overhead is 
small. 


A shutter speed may be given for the camera with the -shutter option on the command line or 
shutter in the options statement, with the default speed of zero turning motion blurring off, 
regardless of the presence of motion transformations or motion vectors in the scene. The shutter 
opens instantaneously at time zero and closes after the shutter speed time has elapsed. An object, 
light, or camera moves by the distance defined by its motion transformation plus motion vector 
if the shutter interval is set to 1.0. The motion blur trail is shorter for shutter values less than 1.0, 
and longer for shutter values greater than 1.0. 


mental ray 3.1 also allows delaying the shutter open time to shift the shutter open time to times 
greater than 0. This allows bidirectional motion blurring in output shaders. 


There are two alternative motion blur algorithms. The regular motion blur algorithm is based 
on temporal oversampling, and is enabled if the shutter period is nonzero (i.e. the shutter time 
is greater than the shutter delay time). The “fast motion blur”>* mode is based on coordinated 
spatial and temporal oversampling, which requires far fewer samples (typically by a factor of five) 
for motion blurred pixels. Fast motion blur mode is enabled if the shutter period is nonzero, and 
if the time contrast is set to 0. In fast motion blur mode, min samples is forced to be equal to max 
samples. 


1.24 Sampling Algorithms 


Jittering, motion blurring, area light sources, and the depth-of-field lens shader are based on 
multiple sampling that is based on varying the sample locations in time, 2D or 3D space. mental 
ray offers a proprietary implementation of the Quasi-Monte Carlo method for achieving these 
variations. Sample locations in time, 2D and 3D space are deterministically chosen on fixed 
points that ensure optimal coverage of the sample space. The algorithm is similar to fixed-raster 
algorithms, but avoids the regular lattice appearance of such algorithms. The resulting images are 
identical if the scene is re-rendered with the same options due to the deterministic nature of the 
algorithm. 


Quasi-Monte Carlo methods can be succinctly described as strictly deterministic sampling 
methods. Determinism enters in two ways, namely, by working with deterministic points rather 
than random samples and by the availability of deterministic error bounds ([Niederreiter 92]). 


1.25 Rasterizer>’ 


mental ray 3.2 and later support a rendering algorithm called Rapid Motion, which was rewritten 
in mental ray 3.4 and renamed rasterizer. Its primary difference to regular scanline rendering 1s 
its separation of sampling and sample compositing (also called sample collection). Without the 
rasterizer, mental ray selects spatial and temporal sample points (eye rays) on the image plane in 
the shutter interval. If an object moves, it will appear in multiple samples at different points in 
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time. Since rendering time is roughly proportional to the number of samples, it rises quickly if 
an object moves quickly. 


The rasterizer works by sampling all objects at a fixed time. If the object moves, these sample 
results are cached and re-used at every point the object passes over. The cache is tied to the 
geometry: 


e a number of sample points is selected on each triangle based on the visibility, size, and 
orientation of the triangle. These points are then individually shaded by calling the material 
and volume shaders as usual. The results are stored. Care is taken not to shade points hidden 
behind other geometry. 


e The image plane is scanned, and all cached shading results are composited to pixels. If an 
object moves, its shading results are simply used multiple times instead of re-shading it. 


This late compositing and re-using of shading results has several important consequences: 


e If the material shader traces rays with shader API functions like mi_trace_reflection, the 
result is re-used at all points the object moves across. This has the effect that the object 
appears to “drag” reflections and refractions with it. For example, if a mirror that is 
coplanar to the image plane moves sideways, its edges are always blurred, but the objects 
being reflected would be blurred only with the rasterizer. 


e Transparency (mi_trace_transparent) can be calculated by the regular scanline algorithm 
without tracing rays, by following the chain of depth-sorted triangles behind the current 
point on the image plane. Since the rasterizer shades points on triangles one by one, and 
does the depth sorting at the later compositing stage, mi_trace_transparent will always 
return false and transparent black. As long as the shader does not do nonstandard linear 
compositing, this gives the same results, but if the shader makes decisions such as casting 
environment rays based on the value returned by mi_trace_transparent, unexpected results 
may happen. 


e In particular, shaders that implement matte objects will not work without modification. 
Matte objects are placeholders for later compositing outside of mental ray; like transparent 
cut-outs where live action will be added later. Since the rasterizer ties its stage-two 
compositing to the alpha component of the RGBA color returned by the material shader, 
it will fill in such cut-outs. To avoid this, a shader may use the new m1_opacity_set function 
to define the opacity for the compositing stage independently of the returned alpha value. 
A matte object would have alpha of 0 but would set an opacity of 1. There is also an mi_ 
opacity_get function to support cooperating shaders in Phenomena. 


The rasterizer is enabled with the command-line option -scanline rapid or the statement 
scanline rapid in the options block of the scene file. mental ray 3.4 controls the sampling 
rate with the normal maximum sampling parameter (second argument of -samples or samples), 
and the number of samples collected during the compositing stage with -samples_collect or 
samples collect, which take an integer argument that specifies the number of shading results 
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to collect per pixel, per pixel dimension. The default collect rate is 4, yielding 16 samples per 
pixel. 


If there are fewer shading results available than required by the collect rate, more shading points 
are added. This can have the result of rendering performance growing with the collect rate 
initially, despite (more precisely, because of) a low sampling setting, and then becoming almost 
independent of the collect rate. 


Due to the different sampling patterns, it is not a good idea to use multipass rendering with passes 
that use the rasterizer together with passes that do not use the rasterizer. 


1.26 OpenGL Acceleration 


By default, mental ray uses a scanline rendering algorithm for primary rays when no lens shaders 
are present that modify the ray direction. This algorithm can cope with both static and motion 
blurred scenes. In addition, mental ray supports OpenGL®° hardware to further accelerate 
scanline rendering of static scenes (without motion blurring). If the master host provides OpenGL 
acceleration with sufficient resolution, mental ray can use this to generate acceleration data that 
is subsequently used during regular rendering. This combines the speed of a hardware OpenGL 
accelerator with the full shading capabilities of mental ray, and is particularly effective for scenes 
with high polygon counts. 


Shadow maps can also be rendered with OpenGL acceleration. This is particularly effective in 
mental ray 2.1 since shadow maps need no shading. Most of the computation involved is then 
performed by the OpenGL system, which greatly improves performance. mental ray 3.0 renders 
only small portions of shadow maps on demand, which in some cases is faster than letting 
OpenGL render the entire shadow map at once. 


However, the accuracy of OpenGL acceleration is generally slightly lower than that of the 
standard software scanline rendering algorithm. Also, OpenGL acceleration is limited by the 
allowable OpenGL image resolution. 


1.27. Color Calculations 


All colors in mental ray are given in the RGBA color space and all internal calculations are 
performed in RGBA. The alpha channel is used to determine transparency; 0 means fully 
transparent and 1 means fully opaque. mental ray uses premultiplied colors, which means that 
the R, G, and B components are scaled by A and may not exceed A if A is less than 1.0. This 
becomes significant only when colors are stored in 8-bit or 16-bit frame buffers because the 
store operation requires quantization and clipping of arbitrary floating-point values to the fixed 
integer ranges of the frame buffer formats. Optionally, RGBA colors may be stored in the output 
image in non-premultiplied form to increase the precision of highly transparent pixels, but by 
convention, mental ray and all shaders work with premultiplied colors (there is no precision loss 


>OpenGL is a registered trademark of Silicon Graphics, Inc. 
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here because mental ray works with floating-point values). Premultiplication is used to simplity 
compositing operations. 


Internally, colors are not restricted to the unit cube in RGB space. As a final step before output, 
colors are clipped using one of two methods. By default, the red, green and blue values are simply 
truncated. Optionally, colors may be clipped using a desaturation method which maintains 
intensity (if possible), but shifts the hue towards the white axis of the cube. Desaturation 
color clipping may be selected with either the -desaturate on option on the command line 
or desaturate on in the options block in the scene. The alpha channel is always truncated. 


mental ray also supports three different color clipping modes that control how premultiplied 
colors are clipped before storing in the frame buffer: 


RGB ensures that R, G, and B never exceed alpha by increasing alpha if necessary, and 
preserving R, G, and B. 


alpha makes the same guarantee, but reduces R, G, and/or B to preserve the alpha channel. 
raw applies no color clipping whatever. 
In any case, the result is clipped into the 0...1 range. 


As a special case, mental ray supports the floating-point TIFF image file format, and a proprietary 
floating-point format (ctfp), that do not require any quantization, clipping, or loss of precision. 
Theretore, desaturation and color clipping are never applied. 


mental ray 3.1 also supports the RGBE high dynamic range color data format. Its stores RGB 
colors (no alpha) as floating-point values with an 8-bit mantissa and an 8-bit shared exponent. 
The shared exponent allows a large value range from 0 to 10°° (actually more, but the internal 
calculations use floats), and has the effect that the ratio between the largest and the smallest 
component cannot exceed 255. It combines the storage efficiency of 8-bit RGB with the ability 
to store values greater than 1.0. 


1.28 Frame Buffers 


mental ray can generate more than one type of image. There are up to five main frame buffers: 
for RGBA, depth, normal vectors, motion vectors, and labels. The depth, normal vector, motion 
vector, and label frame buffers store the Z coordinate, the normal vector, the motion vector, and 
the label of the frontmost object at each sample of the image. If multiple samples are taken for 
a pixel, the frame buffer value for that pixel may be either any one sample value, or a blend 
of all samples. The number and type of frame buffers to be rendered is controlled by output 
statements. Output statements specify what is to be done with each frame buffer. If a frame buffer 
is not listed by any output statement, it is not rendered (except for RGBA, which always exists). 
There are two types of output statements, those specifying output shaders and those specifying 
files to write. 
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There are also up to eight user-defined frame buffers that can be defined with any data type, 
using a frame buffer statement in the options block. In mental ray 3.4, the limitation to eight 
user-defined frame buffers has been removed. 


mental ray versions up to 3.3 store frame buffers in memory. mental ray 3.3 uses a more efficient 
storage format that prevents memory usage from growing while rendering proceeds. mental ray 
3.4 and later store frame buffers in frame buffer files on disk to conserve memory, using memory 
mapping to avoid the overhead of actually storing data on rotating media if memory allows it. 
Frame buffer files are stored in the directory specified with the -fb_dir command line option; if 
none is given the directory specified in the TMPDIR or TEMP environment variables is used. Frame 
buffer files permit very large frame buffers, or very large numbers of frame buffers, without being 
limited by available memory. 


This introduces an incompatibility for output shaders. The list of frame buffer is no longer 
available as a fixed array in the state, so output shaders need to be rewritten for mental ray 3.4 to 
use special frame buffer access functions. 


Frame buffer files are removed from disk when rendering has finished. 


1.29 Output Shaders 


Output shaders are user-written functions that can be linked at runtime that have access to every 
pixel in all available frame buffers after rendering. They can be used to perform operations like 
post-filtering or compositing. 


Files to write are specified with data type, file format and file name. If the data type is omitted a 
default data type is used that is assumed to be the “best” type for the given image format. This 
default type is marked “*” in the table below. The data type implies the frame buffer type. There 
are special file formats for depth, vector, and label files, in addition to a variety of standard color 
file formats. By listing the appropriate number and type of output statements, it is possible to 
write multiple files. For example, both a filtered file and the unfiltered version can be written 
to separate files by listing three output statements: one to write the unfiltered image, one that 
runs an output shader that does the filtering, and finally another one to write the filtered image. 
Output statements are executed in sequence. 


The following file formats are supported: 


description 
Softimage color 
— Softimage depth map (write only) 
RLE Alias color 
RLE Silicon Graphics 8-bit RGBA color 
RLE Silicon Graphics 8-bit RGB color 
Silicon Graphics 16-bit RGBA color 
Silicon Graphics 16-bit RGB color 


format 


type 


compress 
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pe 


rla 
rlb 
picture 


hdr 
ppm 
tga 
bmp 


compress 
JPEG 
RLE 
RE 


* 


+ + + + Be OR OR A oe 


* 


RLE 
KLE 
BLE 
RLE 
KLE 
RLE 


RLE 
KLE 
ae 
RLE 
RLE 
Pio 
LE 
KLE 
RLE 
RLE 
KLE 
RLE 
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description 

JFIF picture 

Portable Network Graphics 8-bit RGB color?” 
Portable Network Graphics 8-bit RGBA color?” 
OpenEXR?°>? 8-bit scalar 
OpenEXR?°? 8-bit RGB color 
OpenEXR?°? 8-bit RGBA color 
OpenEXR?> 16-bit scalar 
OpenEXR?? 16-bit RGB color 
OpenEXR?>? 16-bit RGBA color 
OpenEXR?? 32-bit scalar 
OpenEXR?**? 32-bit RGB color 
OpenEXR?**? 32-bit RGBA color 
OpenEXR?°? depth map 

OpenEXR?>**? normal-vector map 
OpenEXR°*? motion-vector map 
8-bit RGBA TIFF 

16-bit RGBA TIFF 

floating-point RGBA TIFF°* 

8-bit RGB TIFF 

16-bit RGB TIFF 

floating-point RGB TIFF°* 

8-bit RGBA TIFF 

16-bit RGBA TIFF 

floating-point RGBA TIFF°* 

8-bit RGB TIFF 

16-bit RGB TIFF 

floating-point RGB TIFF°* 

Alias Maya 8-bit RGB image? 

Alias Maya 8-bit RGBA image*'! 
Alias Maya 16-bit RGB image?! 

Alias Maya 16-bit RGBA image"! 
Alias Maya float RGBA image’? 
Alias Maya 8-bit alpha 

Alias Maya 16-bit alpha 

Alias Maya floating-point alpha?’ 
Alias Maya depth map 

8-bit or 16-bit Utah/Wavefront color, type A 
Utah/Wavetront color, type B 
Dassault Systemes CATIA PICTURE 
Radiance high dynamic range color, 8-bit RGB color? 
Portable pixmap, 8-bit P6 binary 
Targa color 


MS Windows and OS/2 color 
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type compress description 

qntpal | rgb YUV ~~ Abekas/Quantel, PAL (720576) 

qntntsc | rgb YUV ~~ Abekas/Quantel, NTSC (720x486) 

ct rgba _ mental images 8-bit color (3) 
rgba_16 —- mental images 16-bit color (6) 
rgba_tp -- mental images floating-point color (11) 
a — mental images 8-bit alpha (4) 
a_16 — mental images 16-bit alpha (7) 
atp _ mental images floating-point alpha?"'(15) 
vta — mental images alpha basis vectors (5) 
vts — mental images intensity basis vectors (5) 
Z —- mental images depth map (8) 
n = mental images normal-vector map (9) 
m — mental images motion-vector map (12) 
tag -— mental images normal-vector map (10) 
bit — mental images mask bitmap (13) 
rgbe — mental images HDR color, 8-bit RGB color?! (14) 
any a mental images memory map 


null, deleted on close, write only 


* OpenEXR° in mental ray 3.4 supports the compression modes RLE (default), PIZ (wavelet- 
based), ZIP, and PXR24’. The first three are lossless; PXR24 is lossy if the written data is stored 


The distribution of OpenEXR requires the following copyright notice: 
Copyright (c) 2002, Industrial Light & Magic, a division of Lucas Digital Ltd. LLC 
All rights reserved. 


Redistribution and use in source and binary forms, with or without modification, are permitted provided that the 
following conditions are met: 


e Redistributions of source code must retain the above copyright notice, this list of conditions and the following 
disclaimer. 


e Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following 
disclaimer in the documentation and/or other materials provided with the distribution. 


e Neither the name of Industrial Light & Magic nor the names of its contributors may be used to endorse or 
promote products derived from this software without specific prior written permission. 


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WAR- 
RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN 
NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, IN- 
DIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
OF SUCH DAMAGE. 


’The distribution of the PXR24 compressor requires the following copyright notice: 
Copyright (c) 2004, Pixar Animation Studios 
All rights reserved. 


Redistribution and use in source and binary forms, with or without modification, are permitted provided that the 
following conditions are met: 
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in full floating-point precision and lossless otherwise. mental ray 3.3 and earlier always uses ZIP 
compression. 


Each of these file formats implies a particular default data type (the first entry in column 
“Supported data types”); for example, "jpg" implies 8-bit RGB, and "zt" implies Z. The default 
data type may be overridden by explicitly specifying another data type, such as a 16-bit type, in 
the output statement, as long as it is supported and appears in the above table. mental ray will 
adjust its frame buffer list to compute the requested types. For example, the standard RGBA 
frame buffer stores 8 bits per component by default, but if any output statement references a 
16-bit type, the RGBA frame buffer also switches to 16 bits. 


The null file format is useful to create a stub file during rendering, that can be used to attach the 
imf disp viewer, without leaving the file on disk when rendering finishes. 


The rgb_h and rgba_h image types are supported only for OpenEXR output statements. They 
cause the data to be written to the OpenEXR file in half-float format. mental ray’s frame buffer 
is stored in full floating point format. This allows the full dynamic range without the storage 
overhead of storing full floating-point values in the OpenEXR file. mental ray 3.3 does not 
support half-float frame buffers. 


The RGBE high dynamic range color data type*' can store RGB data whose components may 
exceed the value of 1.0, which is the normal limit for standard RGB data. There are two specialized 
file formats (HDR and CTH) for RGBE, but mental ray will also allow storing RGBE data in 
any 8-bit RGBA format, such as SGI RGB. This will result in images that cannot be displayed by 
standard viewing programs because they would interpret the data as RGBA, but it has become 


common practice to use such formats to transport RGBE data to other tools that understand 
RGBE. 


e Redistributions of source code must retain the above copyright notice, this list of conditions and the following 
disclaimer. 


e Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following 
disclaimer in the documentation and/or other materials provided with the distribution. 


e Neither the name of Pixar Animation Studios nor the names of its contributors may be used to endorse or promote 
products derived from this software without specific prior written permission. 


THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WAR- 
RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN 
NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, IN- 
DIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 
OF SUCH DAMAGE. 
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The available data types are: 


8 RGBA color 
16 RGBA color (16 bits per component) 
32. RGBA color (floating-point) 

8 RGB color 
16 RGBcolor (16 bits per component) 

32. RGB color (floating-point) 

8 high dynamic range RGB color 
8 Alpha channel 
16 Alpha channel (16 bits per component) 
32. ~=Alpha channel (floating-point)>:! 

8 synonymous with a 
16 synonymous with a_16 
32. synonymous with a_fp°! 

32. ~~ depth channel 
32 normal vectors 
32 motion vectors 
32 label channel 

16 UV vector texture 
synonymous with vta 
bitmask channel 


32. coverage of most important object’* 


— 


The difference between "vta" and "vts", and betweenn and n, is significant only when automatic 
conversions are done. The file contents are identical except for the magic number in the file header. 


The floating-point RGBA data type "rgba_fp" allows color and alpha values outside the normal 
range (0,...1), and no dithering is applied even if explicitly enabled. In contrast, any conversion 
to the 8-bit or 16-bit formats will clamp values outside this interval. Note that dithering reduces 
the effectivity of RLE compression. 


All mental images file formats contain a header followed by simple uncompressed image data, 
pixel by pixel beginning in the lower left corner. Each pixel consists of one to four 8-bit, 16-bit, or 
32-bit component values, in RGBA, XYZ, or UV order. The header consists of a magic number 
byte identifying the format, a null byte, width and height as unsigned shorts, and two unused 
null bytes reserved for future use. All shorts, integers, and floats are big-endian (most significant 


byte first). 


mental ray can combine samples within a pixel in different ways. The combination of existing 
samples can also pad the frame buffers to “bridge” unsampled pixels. Interpolation of colors, 
depths, normals, and motion vectors means that they are averaged, while interpolation of the labels 
means that the maximum label is used (taking the average label is not a good idea). Interpolation 
of depths only takes the average of non-infinite depths, and interpolation of normals and motion 
vectors only takes the average of vectors different from the null vector. Interpolation is turned 
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i<9 9 


on by writing a “+” in the beginning of the output type and turned off by writing a “—” there. 
For example, to interpolate the depth samples, write “+z” in the output statement: 


last color 

average color 

lowest depth 

average depth, excluding infinite depths 


last normal 

average normal, excluding null vectors 

last motion vector 

average motion vector, excluding null vectors 


last label 


maximum label 


If interpolation is turned off for a frame buffer, the last sample value (color, normal, motion 
vector, or label) within each pixel is stored, and pixels without samples get a copy from one of 
the neighbor pixels. Interpolation off for depth images is an exception: rather than using the last 
sample depth, the min depth is used — this can be useful for compositing. Interpolation is on by 
default for color frame buffers (including alpha and intensity frame buffers) and off by default 
for depth, normal, motion vector, and label frame buffers. 


1.30 Pixel Coverage 


mental ray 3.x supports an extra data type "coverage" that creates a separate frame buffer 
containing the fraction of each pixel covered by the most samples in that pixel. Oversampling 
often takes several samples (primary rays) in a pixel for anti-aliasing; the samples are averaged. 
At points where one object overlaps another, one object may account for more of the pixel than 
the other, which might just touch a corner of the pixel. In such a case, the coverage frame buffer 
specifies exactly how much of the pixel the “more important” object covers. This is a number in 
the range 0 (the pixel is empty) to 1 (an object covers the pixel completely). If the coverage buffer 
is written to a file, a scalar format such as st should be chosen. mental ray can also convert to 


RGB/A formats such as TIFF. 


Since mental ray is a point-sampling renderer, the precision is bounded by the number of samples 
taken, which depends on the oversampling settings (samples option). Two objects are considered 
different if their object tags differ. Object tags are defined with tag statements in the object 
definition in the scene file. 


If coverage calculation is enabled by adding the appropriate output statement, the depth, normal, 
motion, and tag frame buffers, if also enabled and marked with a “-” (which is the default), are 
guaranteed to come from the object that had the most coverage. 
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1.31 Contours 


Contour lines can be an important visual cue to distinguish objects and accentuate their forms 
and spatial relationship. Contour lines are especially useful for cartoon animation production. 


Contours can be placed at discontinuities of depth or surface orientation, between different 
materials, or where the color contrast is high. The contour lines are anti-aliased, and there can be 
several levels of contours created by reflection or seen through semitransparent materials. 


The contours can be different for each material, and some materials can have no contours at all. 
The color and thickness of the contours can depend on geometry, position, illumination, material, 
frame number, and various other parameters. 


The resulting image may be output as a pure contour image, a contour image composited onto 
the regular image (in raster form in any of the supported formats), or as a PostScript file. 


It is not possible to render contours in a scene with motion blur or rasterizer (formerly called 
Rapid Motion), and jittering must be turned off. Contour rendering is multithreaded, but cannot 
make use of slave hosts. Contour rendering requires the default box 1 1 filter. 


Contour shaders are called while the normal color image is created. Contours are computed using 
information stored by a contour store shader. The contour store shader is called once for each 
intersection of a ray with a material. The position of contours are determined by a contour contrast 
shader. It compares the two sets of information for a pair of points, and decides whether there 
should be a contour between the points. The color and thickness of the contours are determined 
by contour shaders. 


1.32 Caustics 


Caustics are light patterns that are created when light from a light source illuminates a diffuse 
surface via one or more specular reflections or transmissions. Examples are: 


e The light patterns created on the bottom of a swimming pool as light is refracted by the 
water surface and reflected by the diffuse pool bottom. 


e Light being focused by a glass of water onto a diffuse table cloth. 


e The light emanating from the headlights of a car: the light is emitted by the filament of a 
light bulb, reflected by a parabolic mirror reflector (thereby being focused in the forward 
direction), and reflected by the diffuse road surface. 


Caustics cannot be simulated efficiently using standard ray marching since predicting the potential 
specular paths to a light source from any given surface is a difficult (and in many situations 
impossible) task. To overcome this problem mental ray uses a photon map. The photon map is 
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generated in a preprocessing step in which photons are emitted from the light sources and traced 
through the scene using photon tracing. 


The emission of photons is controlled using either one of the standard photon emitters for point 
lights, spot lights, directional lights, and area lights, or by using a user defined photon emitting 
shader. 


A photon leaving the light source can be reflected or transmitted specularly by objects. The 
photon is traced through the scene until it either hits a diffuse surface or until it has been reflected 
or transmitted a maximum number of times as indicated by the photon trace depth. When a 
caustic photon hits a diffuse object it is stored in a caustic photon map and not traced any further. 


To control the behavior of photons as they hit objects in the scene, it is necessary to attach 
photon material shaders to these objects. Photon material shaders are similar to normal material 
shaders with the main difference being that they trace the light in the opposite direction. Also, a 
photon shader distributes energy (flux) instead of collecting a color (radiance). Another important 
difference is the fact that photon material shaders do not need to send light rays to sample the 
contribution from the light sources in the scene. 


In order to use the photon shaders, it is necessary to include the appropriate shader declaration 
file, such as physics.mi for physics-based material shaders and photon shaders from the physics 
shader library in the standard distribution. 


To turn caustics on, specify caustic oninthe options or use the command-line option -caustic 
on. 


1.32.1 Light Sources 


Photons are emitted from the light sources in the scene. It is necessary to attach some extra 
information to each light source to control the energy being distributed into the scene (and/or 
the number of photons emitted). 


To generate caustics from a particular light source, one must specify the energy emitted by the 
light source. This is given by the energy keyword. The energy is the flux distributed by the light 
source and it will be distributed into the scene by each photon which will carry a fraction of the 
light source energy. If the energy is zero (the default), no photons will be emitted. 


Another important factor is the number of photons to be generated by this light source. This 
can optionally be specified using the caustic photons keyword (10000 photons is the default). 
This will be the number of photons stored in the photon map and thus a good indication of the 
quality of the generated caustics. It is also a direct indication of the memory usage which will 
be proportional to the number of photons in the photon map. For quick, low-quality caustics, 
caustic photons 10000 is adequate, for medium quality 100000 is typically needed, and for 
highly accurate effects, caustic photons 1000000 can be necessary. It is also possible to specify 
a second integer, which is the maximum number of photons to be emitted from the light source, 
or only the number of emitted photons by setting the first integer to zero (mental ray 2.1.37 and 
up). By default there is no upper limit (indicated by the value 0), in which case emission will 
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continue until the specified number of photons have been stored. Notice that the emitted number 
of photons and the preprocessing time is most often proportional to the number of photons 
generated in the photon map. 


For most light sources, the distribution of energy using photons will give the natural inverse square 
fall-off of the energy. This might be an unwanted effect since some light shaders implement a 
linear fall-off. It can be avoided by using the exponent keyword. If the exponent is p, the fall- 
off is 1/7’, where r is the distance to the light source. Exponent values between 1 and 2 make 
the indirect light less dependent on distance. Exponents of less than 1 is not advisable, as it often 
gives visible noise. Exponent 2 is the default. Note that this violates the conservation-of-energy 
law, and could cause bright spots from distant light sources in unexpected locations. 


The following is an example of a light that uses the soft_point light shader and is capable of 
generating caustics: 


light “caustic-lighti" "soft_point" ( 


"COLO; 1.0 1.0°0.95, 
"shadow" on, 
"“factor™ 0.6; 
"atten" on, 
*Start” 16.0, 
"stop" 200.0 
) 
origin 20.0 30.0 -40.0 
energy 700 700 700 
caustic photons 100000 
exponent La 
end light 


An example of a light source which uses the inverse square fall-off to compute illumination (and 
the default 10000 photons) is: 


light "pointi" "physical_light" ( 


"color" 700.0 700.0 700.0 
) 
origin 20.0 30.0 -40.0 
energy 700 700 700 
end light 


It is important to note the difference between color and energy. color is the power of the direct 
illumination, while energy will be the power of the caustic. It is therefore possible to tune the 
brightness of caustics to make them more or less visible. 


If area light source information, such as a rectangle statement, is added to the light source 
definition, both the direct and global illumination will be emitted from an area light source. This 
tends to make caustics more fuzzy. 
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To emphasize caustics, the energy of the light sources can be higher than their colors (that 
determine the direct illumination). If, for whatever reason, the user wants to have the sources of 
caustics to be at different positions than the sources of direct illumination, this is possible too. It 
might also be that a single light source is sufficient for the caustics, while several light sources are 
needed to fine-tune the direct illumination. 


1.32.2 Objects 


By default, all objects can cast and receive caustics, that is, photons are emitted in all directions 
from a point light source (and with all possible origins for a directional light source). For some 
scenes, this is fine — for example if a point light source is surrounded by specular surfaces. But for 
some scenes, it is very inefficient — for example a point light far away from a single small specular 
object. 


To generate caustics more efficiently in such scenes, objects can be flagged such that the photons 
are only emitted towards certain objects and stored only on selected objects. Objects are then 
divided into caustic-casting (caustic 1 flag) and caustic-receiving (caustic 2 flag), or both 
(caustic 3 flag), or neither(caustic 0 flag). For example, caustics on the bottom of a swimming 
pool require a caustic-casting water surface and a caustic-receiving pool bottom. Objects can also 
be flagged caustic off, which means that caustic photons will not hit them at all (the objects will 
be “invisible” to caustic photons), or flagged caustic on which is the same as caustic 3. The 
caustic mode is an object attribute. Photons are emitted only in the direction of caustic-casting 
objects, and only stored on caustic-receiving objects. 


To use this optimization requires that the default object caustic flag (specified in the options) 
is set to something different than 3 (which is the default value, enabling all objects to cast and 
receive caustics). 


For example, the options can contain 


caustic on 
caustic 0O 


The definition of a caustic-casting object can for example begin as 


object "revol4" 
caustic 1 visible shadow reflection refraction tag 13 


The material of a caustic-casting object has to be mainly specular (little or no diffuse reflection), 
and for most materials, the sum of reflection and transparency should be close to or larger than 
1. For caustics generated by refraction, the index of refraction has to be different from 1. For 
example, the index of refraction for water is 1.33, for glass 1.5 to 1.7, and for diamond 2.42. 
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1.32.3. Material Shaders and Photon Shaders for Caustics 


mental ray comes with three material shaders that support caustics (and global illumination) 
soft-material, dgs-material and dielectric_material. Their photon shader equivalents are soft- 
material photon, dgs_material_photon and dielectric_material_ photon. When defining a material 
it is necessary to specify both the regular material shader and the photon shader. Most often, 
however, the photon shader can inherit the parameter setting from the regular material shader. In 
addition to these six shaders, users can write new material and photon material shaders. 


1.32.4 Physically Plausible Material Shaders 


A pair of material shaders that emphasize physical accuracy are dgs_material and dgs_material_ 
photon. They simulate three types of reflection: 


e diffuse (Lambert’s cosine law), 
e glossy (isotropic or anisotropic), 


e specular (mirror), 


as well as the corresponding types of refraction and translucency, and any combination of these. 
Therefore, they can simulate mirrors, glossy paint or plastic, anisotropic glossy materials such 
as brushed metal, diffuse materials such as paper, translucent materials such as frosted glass, and 
any combination of these. 


Each material declaration using dgs_material has to havea photon "dgs_material_photon" () 
statement. These two shaders should be used together for physical accuracy. An example is: 


material "mirror" opaque # ideal mirror material 
"dgs_material" ( 
"specular" L.@ 23-50; 1.0; 


"lights" ["arealight-i"] 
) 
shadow "dgs_material" () 
photon "dgs_material_photon" () 
end material 


Another pair of physically based shaders is dielectric_material and dielectric-material_photon. 


For further details on dgs_material, dielectric_material, and their photon shaders, see the 
documentation of the Physics Shader Library. 
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1.32.5 Shader Functions 


There are two functions that are especially important to writers of photon shaders. 


The shader interface function mi_choose_scatter_type chooses a scatter type for a photon based 
on the probabilities for diffuse, glossy, and specular reflection and refraction. It can also choose 
absorption, that is, that the photon should be traced no further. The function also ensures a 
correct energy level in the scene by altering the reflection coefficients according to the scatter 
choice. 


During regular ray marching, material shaders of caustic-receiving objects should call the mz- 
compute irradiance function to “pick up” the illumination caused by photons reaching the object 
during preprocessing. 


1.32.6 Fine-Tuning Caustics 


The number of photons used to estimate the caustic brightness can be changed with the global 
option caustic accuracy. The accuracy controls how many photons are considered during 
rendering. The default is 100; larger numbers make the caustic smoother. There is also an optional 
radius parameter. The radius controls the maximum distance at which mental ray considers 
photons. For example, to specify that at most 200 photons should be used to compute the caustic 
brightness, and that only photons within 1 scene unit away should be used, specify: 


caustic accuracy 200 1.0 


in the options. (Similar accuracy parameters are available for global illumination, volume caustics 
and global illumination, and final gathering.) 


Accuracy parameters can be used to select two fundamentally different sampling policies. If R 
is relatively large (as is the default), the overall limiting factor becomes N and R only catches 
runaway situations with very few photons. Since darker areas have fewer photons than brighter 
areas, the effective radius within which the N photons are found is larger in dark areas. The 
effect is that low intensity areas will have less detail than high intensity areas. Also, increasing the 
number of photons in the scene will result in the effective radius becoming smaller, so if N is not 
adjusted to compensate, the same amount of noise will be seen, only on a smaller scale. 


The other policy is to select R small, on the scale of the detail the user wishes to see. N is then 
kept high, or even set to 0 (unlimited). In this case, a constant radius is examined which results in 
the scale of the detail remaining constant between light and dark areas. Increasing the number of 
photons in the map will have the effect of reducing the error noise. In practice, one will often use 
a combination of the two, with a small radius to get detail in dark areas, and N set at a moderate 
value to speed up rendering. Irrespective of the chosen policy, a large effective radius gives less 
noise, but a more blurred result. To decrease the noise without blurring detail, it is necessary to 
increase the number of photons in the photon map. It is very instructive to explore the effect of 
setting these options with the aid of the diagnostic photon option since the false color image it 
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generates shows the difference in estimated density more clearly. For fast previewing of caustics 
it can be useful to use N=20. 


1.33. Global Illumination 


Global illumination is the simulation of all light interreflection effects in a scene (except caustics). 
This includes effects such as color bleeding: if a red table is next to a white wall, the white wall 
gets a slightly pink tint. This effect is not possible with ordinary ray tracing algorithms. But if 
the pink tint is lacking in an image, the image looks fake, even though it might be hard to point 
out precisely why. Global illumination effects are subtle but add realism to a scene. 


Simulation of global illumination has at least two distinct uses: 


e Physically accurate simulation of the illumination in an environment. For example the light 
distribution inside an office building. 


e Visually pleasing lighting effects for applications in the entertainment industry. Here 
physical accuracy is not the most important aspect, the images just have to look believable. 


The computation of global illumination requires photon tracing, just like computation of caustics. 
In fact, the same photon material shaders can be used. Since caustics are treated separately in mental 
ray, the global illumination simulation does not include caustics. So if all light interreflections 
should be simulated, both global illumination and caustics must be enabled. 


The photons stored during global illumination simulation are stored in a separate photon map, 
the global illumination photon map. When the material shader calls mi_compute irradiance, 
the irradiance from both the caustics photon map and the global illumination photon map are 
computed. 


To turn global illumination on, specify globillum on in the options or give command-line 
option ~globillum on. 


1.33.1 Light Sources 


Each light source that should emit global illumination should have an energy statement (just 
as for caustics). Each light source can also optionally have a globillum photons statement to 
specify how many photons should be emitted, or specify emitted photons only by setting the first 
number to zero (similar to caustic photons for caustics). The default value is 100000 globillum 
photons. For example: 


light "globillum-light" "physical_light" ( 
*color”™ 700.0 700.0 700.0 
) 
origin 20.0 30.0 -40.0 
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energy 700 700 700 
globillum photons 100000 
end light 


1.33.2 Objects 


By default, all objects can participate in global illumination computations. This is necessary for 
simulation of real global illumination. However, sometimes one might just be interested in color 
bleeding from one object to another, and the rest of the scene does not need to participate in the 
global illumination simulation. 


To simulate global illumination more efficiently in such cases, objects can be flagged such that 
the photons are only emitted towards certain objects and stored only on selected objects. 
Objects are then divided into globillum-casting (globillum 1 flag) and globillum-receiving 
(globillum 2 flag), or both (globillum 3 flag), or neither (globillum 0 flag). For example, 
color bleeding from a red diffuse table onto a diffuse white wall requires a globillum-casting table 
and a globillum-receiving wall. Objects can also be flagged globillum off, which means that 
globillum photons will not hit them at all (the objects will be “invisible” to globillum photons), 
or flagged globillum on which is the same as globillum 3. The globillum mode is an object 
attribute. Photons are emitted only in the direction of globillum-casting objects, and only stored 
on globillum-receiving objects. 


To use this optimization requires that the default object globillum flag (specified in the options) 


is set to something different than 3 (which is the default value, enabling all objects to cast and 
receive global illumination). 


1.33.3, Fine-Tuning Global Illumination 


To change the number of photons used to compute the local intensity of global illumination, 
specify aglobillum accuracy (and optionally a maximum radius) in the options. For example, 


globillum accuracy 300 2.0 


The default number is 500; larger numbers make the global illumination smoother but increase 
render time. The default radius depends on the scene extent. 


1.34 Final Gathering 


Final gathering is a technique for estimating global illumination for a given point by either 
sampling a number of directions over the hemisphere over that point (such a set of sample is 
called a final gather point), or by averaging a number of nearby final gather points since final 
gather points are too expensive to compute for every illuminated point. 
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For diffuse scenes, final gathering often improves the quality of the global illumination solution. 
Without final gathering, the global illumination on a diffuse surface is computed by estimating 
the photon density (and energy) near that point. With final gathering, many new rays are sent 
out to sample the hemisphere above the point to determine the incident illumination. Some of 
these rays hit diffuse surfaces, and the global illumination at those points is then computed by 
the material shaders at these point, using illumination from the globillum photon map if available 
and other material properties. Other rays hit specular surfaces and do not contribute to the final 
gather color (since that type of light transport is a secondary caustic). Tracing many rays (each 
with a photon map lookup) is very time-consuming, so it is only done when necessary — in most 
cases, interpolation and extrapolation from previous nearby final gathers is sufficient. 


Final gathering is useful in scenes with slow variation in the indirect illumination, such as purely 
diffuse scenes. For such scenes, final gathering eliminates photon map artifacts such as low 
frequency noise and dark corners. With final gathering, fewer photons are needed in the globillum 
photon map and lower globillum accuracy is sufficient since each final gather averages over many 
values of indirect illumination. 


In film production work, final gathering more and more replaces photon mapping, except for 
caustics. Without multiple-bounce effects, which are performed by photons by default and by 
final gathering only if the shaders adjusts the trace depth, tends to have far less impact on the final 
image than the first bounce that final gathering supports by default. Although physical correctness 
is lost, this is often “good enough” for film production, and final gathering is easier to control 
than photons emanating from distant light sources. However, for accurate indoor illumination 
simulations and other CAD-related applications, photon mapping is still the method of choice. 


Final gathering is off by default, but can be turned on in the options. Final gathering is also 
useful without photon tracing; this only takes first-bounce indirect light into account but often 
gives good results where complete physical accuracy is not required. 


To change the number of rays shot in each final gather (and optionally the max distance at which 
a final gathering result can be used for interpolation and the minimum distance at which it must 
be used), specify afinalgather accuracy in the options. For example, 


finalgather accuracy 1000 1.5 0.25 


increases the number of rays and reduces noise in scenes with complex illumination and geometry. 
The default number of rays is 1000. The default maximum distance depends on the scene extent; 
decreasing it will reduce noise but increase render time. The default minimum distance is 10% of 
the maximum distance. 


mental ray 3.4 has changed the final gathering algorithm. It normally achieves better quality 
at higher speed with approximately one-half the number of rays. It is necessary to modify the 
accuracy statements though, for example changing 1000 to 500 above, or rendering times will 
increase. 
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1.35 Volume Caustics 


Volume caustics are caused by light that has been specularly reflected or refracted by one or more 
surfaces and is then scattered by a participating medium in a volume. Examples are: 


e Sunlight refracted by a wavy water surface and then scattered by little silt particles in the 
water. 


e Car fog lamps: light emitted by a bulb filament, reflected by a parabolic reflector, and 
scattered by fog. 


In order to create volume caustics, the same light sources, material shaders, photon shaders, and 
caustic tags as for caustics are needed. But in addition, volume shaders and volume photon shaders 
are needed. For example: 


material "volsurf" opaque # material for surfaces of volume 
"transmat" () 
shadow "transmat" () 
photon "transmat_photon" () 
volume "parti_volume" ( 
"scatter" 0.05 0.05 0.05, 
"“extinceion’ 0.06; 
"lights" ["arealight-i"] 
) 


photonvol "parti_volume_photon" ( 
“scatter” 0.05 0:08 0.06, 
"extinction" 0.05 

) 


end material 


mental ray 3.3 and later do not require the transmat and transmat_photon shaders; they allow 
leaving the material shaders to remain undefined to stop the object from interacting with visible 
rays. Such an object is called a hull object because it acts as a hull for a volume, but is not visible 
itself. 


Photons that get scattered multiple times in the volume are stored in a volume photon map. 
During rendering, volume shaders can call the function mi_compute_volume_irradiance to get 
irradiance from the photons stored in the volume photon map. 


In order to fine-tune the volume caustic, it is possible to change the number of photons that is 
used to compute the indirect light in the volume caustic. This is done witha photonvol accuracy 
statement in the options. The default is 30 photons and a radius that depends on the scene extent. 
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1.36 Global Illumination in Participating Media 


Global illumination in volumes can be used to simulate indirect light interactions in volumic 
media, such as: 


e color bleeding from a colored wall onto gray smoke. 


e multiple light scattering in clouds or other participating media, such as the glow around 
the beam from a car headlight in fog. 


Global illumination in participating media is computed much the same way as global illumination 
on surfaces, except that volume shaders and volume photon shaders are needed. 


To change the number of photons used to compute the local intensity of global illumination in 
volumes, specify a photonvol accuracy (and optionally a radius) in the options (similar to 
volume caustics). 


1.37. Diagnostic Modes 


mental ray supports a number of diagnostic modes that help visualizing and optimizing the 
rendering process. They modify the output image to include grid lines or dot patterns that 
indicate coordinate spaces or sampling or photon densities. These graphs allow simple detection 
of insufficient or excessive sampling densities, and help to tune parameters such as numbers of 
photons or sampling and contrast limits. 


Grid Mode This mode renders a grid on top of all objects in the scene, in object, 
camera, or world space. It’s useful to get an idea of the scene scale and 
to enable rough estimates of distances and areas. 


Photon density mode This mode shows a false color rendering of photon density on all 
materials. This is useful when tuning the number of photons to trace 
in a scene, and to select the optimum accuracy settings for estimation 
of global illumination or caustics. It also works well in combination 


with the Grid Mode described above. 


Samples mode This mode shows how spatial supersamples were placed in the 
rendered image, by producing a grayscale image signifying sample 
density. This is useful when tuning the level and the contrast threshold 
for spatial supersampling. 


BSP mode’* This mode shows the cost of creating and traversing the BSP tree used 
for raytracing. Both the depth and the leaf size can be visualized. If 
the diagnostic image shows that mental ray has been operating near 
the limit in large parts of the image (indicated by red or white pixels), 
this helps tuning the BSP parameters in the options block. 
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Final gathering mode*! _—_ This mode shows final gathering points, as green dots for initial raster- 
space final gathering points, blue dots’* for final gathering points 
from per-object finalgather map files and red dots for render-time 
final gathering points. 


Diagnostic modes are enabled with the -diagnostic option on the command line, or the 
diagnostic statement in the options block in the scene description file. 


1.38 Accelerated Graphics Hardware Rendering? 


mental ray 3.3 and later support hardware rendering. Hardware shading refers to leveraging 
hardware graphics acceleration boards installed in PCs or workstations, available from vendors 
such as NVIDIA, ATI, 3Dlabs, Matrox, SGI, Sun, and others, that can draw 3D geometry at very 
high speed. This document uses the term “hardware” to refer to 3D graphics hardware. 


3D graphics hardware is not accessed by programs directly. An intermediate 3D library is 
used. Two standards exist: OpenGL and DirectX, both of which provide roughly equivalent 
functionality. However, DirectX is not portable and available only for Microsoft Windows, 
while OpenGL is available for a large range of platforms other than Windows that are supported 
by mental ray. Since one of the primary applications of mental ray is its use in large networks 
(“render farms”) and such networks almost never use Windows for various technical reasons, 
OpenGL was chosen for mental ray to access graphics hardware. 


mental ray versions prior to 3.3 already supported OpenGL rendering for a limited form of 
hardware acceleration, primarily for 3D projection and visibility calculations for rendering and 
shadow mapping. The scene was painted using OpenGL, but not with its true surface colors 
but pseudo colors that encode addressing information that tells mental ray for every pixel which 
object and which triangle is in front. mental ray then only needs to perform shading, but not 
intersection calculations. For actual color rendering, the visual quality of hardware shading was 
not acceptable so this was done in software. 


Hardware capabilities have grown significantly since then. It is now possible to perform hardware 
shading with a simple form of procedural shaders. Shaders allow visual effects that go far beyond 
the “plastic look” limitations of older designs. It is now becoming practical to use graphics 
hardware for actual color shading at very high speeds without compromising image quality in 
unacceptable ways. mental ray 3.3 is designed to implement this new approach. 


1.38.1 Hardware vs. Software Rendering 


Ideally, software rendering algorithms should be translatable directly to hardware. However, this 
is not possible because hardware and software rendering use two very different approaches: 


e Software rendering holds the 3D scene to be rendered (or the relevant portions of it) in 
memory, and samples it pixel by pixel or subpixel by subpixel. In other words, the scene is 
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static and always present, but the renderer deals with one pixel or subpixel at a time. 


e Hardware rendering operates the opposite way. All pixels are present at all times, but 
rendering consists of considering the scene one triangle at a time, “painting” each one into 
the frame buffer. The hardware has no notion of a scene; only a single triangle is known at 
any one time. 


Software is completely unconstrained, except by performance considerations, and can perform 
any algorithm whatever. The subpixel loop method is chosen because it allows rendering nonlocal 
effects that require considering different portions of the scene in order to compute a single pixel 
or subpixel. For example, reflections require access to both the reflecting and the reflected object. 
A more complex example is global illumination, which considers the indirect light from all 
surrounding objects to compute the brightness of the subpixel being rendered. Hardware can do 
none of this because it only ever knows one triangle at a time, and has no notion of other objects. 


Hardware rendering uses a limited range of workarounds to address some of these limitations. 
These workarounds typically involve pre-rendering objects into “maps”, which are rectangular 
pixel rectangles encoding properties of other objects and are stored in the graphics hardware in 
the form of texture images. While graphics hardware cannot deal with multiple objects, it can 
deal very efficiently with texture images. Examples for such mapping techniques are: 


e Shadow mapping renders the scene from the viewpoint of each light source, recording only 
the depth of the frontmost object. This can later be used during final rendering to decide 
whether a point is in shadow, if it is farther away from the light than the recorded depth. 
This approach does not work well for area lights that cast soft shadows (shadows with 
fuzzy edges), and it cannot handle transparent objects such as stained glass or smoke. 


e Reflection maps render the scene from the viewpoint of a mirror. This image is then “pasted 
in” when the final render needs to know what is seen in the mirror. This works only for 
flat or near-flat mirrors. 


e Environment maps contain a hemispherical or otherwise complete view of the surroundings 
as seen from the rendered scene. Nearby objects are not normally included. Although 
environment maps represent the scene poorly, and cannot capture the arrangement of 
nearby objects at reasonable computational cost, they are acceptable for highly curved 
reflectors such as chrome trims. 


Workarounds like this have one difficulty: they require a lot of manual preparation and fine- 
tuning to work; for example, deciding on a good environment map. The computer cannot do this 
because while computing a correct map is possible, it would be very expensive and easily defeat 
the expected time savings. 


The driving force behind graphics hardware design is gaming, which involves rendering as 
many triangles per second as possible to a video screen. Also, procedural shading is still quite 
primitive and requires workarounds as described above. This creates some limitations of hardware 
rendering: 
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e Rendered images go to a video screen. Retrieving them to the main memory for further 
processing is often poorly optimized and slow. This can be the main factor limiting frame 
rates. 


e To achieve full speed, the entire renderer must be carefully hand-crafted to the scene being 
rendered. This cannot be done for a general-purpose renderer. 


e Many effects beside the mapping workarounds described above require rendering the scene 
multiple times because the complexity of the effect exceeds the capacity of the hardware. 
This is called “layering” and described in more detail below. This reduces the achievable 
frame rates. 


e Multiple frame buffers are unavailable. Rendering to video only requires RGBA video with 
low bit depth and a depth (Z) buffer. General-purpose production rendering requires many 
frame buffers with high bit depths. 


e Oversampling to reduce “staircase” aliasing is generally slow and has poor quality. The 
subpixels computed are inaccessible; only the final pixel is available. 


e There is no good approach to motion blurring. This is critically important for film 
production. 


e Pixel resolutions are limited. The hardware is designed to drive a video display with limited 
resolution. Film production typically uses images 2000 pixels wide and more. 


e Textures must be stored in the video hardware before use. The available memory is usually 
128 or 256 MB. Film production often uses gigabytes of textures, which requires very slow 


paging. 


e Compatibility between the hardware from different vendors, and even between successive 
hardware generations from the same vendor, is very poor. Although OpenGL hides many 
differences, the most advanced features and the fastest speed paths generally have not found 
an abstraction in OpenGL yet. Hardware development cycles are extremely rapid. 


None of this is mentioned in the literature and sales material for graphics hardware boards. In 
general, it is unrealistic to expect to attain advertised realtime frame rates, often over 100 frames 
per second, for general-purpose rendering without spending the years of custom development 
that game designers generally require. 


Yet, despite all the limitations of hardware rendering, the things it can do are done at extremely 
high speed, sometimes more than a thousand times faster than software. Harnessing this speed 
is the object of the hardware shading support in mental ray 3.3. Although the limitations make 
it impossible to simply switch from software to hardware rendering, much of the advantage 
can be realized with an appropriate combination of hardware rendering and software rendering, 
combining hardware speed with software flexibility. This document describes how mental ray 
does this. 
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1.38.2 Layering 


The key concept for combining hardware with software rendering is layering. It refers to building 
a final image from multiple sub-render passes. The concept is already common in pure hardware 
rendering: a surface might be too complex to be rendered in one pass, so a first render pass may lay 
down the base color, another adds glossy, glow, or fur effects, and a final pass puts highlights on 
top. Each layer accumulates color in the frame buffer. Newer hardware also permits combining 
successive layers in ways other than accumulation of the frame buffer by providing a feedback 
path from the previous layer result to the current layer calculation. 


In this document, the term Layering is extended to also cover pre-rendering of shadow maps and 
and other maps as listed above. Although the result is stored as textures and not accumulated in 
the image frame buffer, the feedback paths in recent hardware designs are beginning to blur this 
distinction. 


Layering does not necessarily involve rendering the entire scene. It is more common to group 
sections of the scene by object or by material. Many objects contain multiple materials, and it is 
fairly expensive to switch materials in the graphics hardware because that may involve reloading 
of textures, lights, shaders, transformation matrices, and other context information. Reloading 
is far slower than rendering triangles. For this reason, object sections are normally sorted by 
material, in addition to normal depth sorting to avoid sending objects that are hidden behind 
others at all. 
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Effectively, hardware rendering is a fairly long sequence of rendering separate object portions, 
many of them multiple times, each time resulting in some form of pixel rectangle. The rendering 
operations form a dependency graph, with pixel rectangles flowing along the edges of the graph: 


color image 


color image + 


depth map color image + 


depth map 


object1, layer 2 object 2 


T 


color image + 
depth map 


object 1, layer 1 


color image 


environment 


shadow map 1 shadow map 2 


Rendering begins at the bottom of the graph because all inputs to a node must be available before 
beginning to calculate the node. Object 1 consists of two layers, one computing illumination (and 
hence needing to know which points are in shadow) and the other adding some extra information 
such as glows. Object 2 is only a single pass illuminated only by one light, but using a chrome 
reflection model that requires an environment map. Both objects are combined to calculate the 
final output image. In practice, such graphs are far larger than this trivial example. 


The design goal of hardware support in mental ray 3.3 is that some of the graph nodes are 
computed in software, and others in hardware. For example, to add global illumination to the 
above graph, a software node would compute the global illumination map (using final gathering 
or photon mapping), then another software node would create a light map to bake the indirect 
light into a texture, which is then used by a hardware node to add to the direct light contribution 
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computed by hardware shading: 


color image 


color image + 


— 
depth map color image + 


depth map 


object1, layer 2 object 2 


color image + 
depth map 


object 1, layer 1 


depth map 


color image 


shadow map 1 shadow map 2 environment 


color image 


light mapper 


photon or fg map 


global illum. 


The shaded nodes are software nodes; the unshaded nodes are hardware nodes. Note that it is 
often possible, as in the case of global illumination maps, to compute the map once and re-use it 
for multiple frames. 


58 1 Functionality 


1.38.3. Speed vs. Quality Tradeoffs 


Since these graphs consist of distinct nodes that communicate only by frame buffers, it is possible 
to switch nodes between hardware and software. This has several applications: 


e Switching by shader: whenever a hardware variant of a shader is available, use it, even if 
it has reduced functionality. This is useful for fast previews. For example, while the user 
interacts with the scene by moving an object, fast preview rendering is done; when the 
interactions stops a high-quality image is rendered and displayed. 


e Switching by layer: speed can be further accelerated by marking layers as optional, for 
example rendering only the base surface without the more expensive Phong highlight layer. 


e Switching by functionality: specific effects can be achieved by switching functional node 
groups between hardware and software rendering. For example, an object may be rendered 
in software with accurate transparent ray-traced shadows, or it may be rendered in hardware 
with nontransparent shadowmapped shadows. In general, any effect that requires surface 
mapping can be switched in this way by rendering the map in software and the mapped 
object in hardware. 


e Switching by object: entire objects and all their associated shaders can be switched. This is 
useful for scenes that are well suited for hardware rendering, except for a small number of 
objects that require the flexibility of software. 


e Layer Persistence: recomputation of software layers can be delayed for some frames. It is 
often sufficient to re-use light maps for multiple frames. Not every node in the graph needs 
to be executed for every frame. 


These modes are a central design goal because they provide a smooth continuous tradeoff between 
speed and quality. Traditionally, hardware rendering was considered to generate images with poor 
quality, good enough for fast games but not for professional video or film production. But in fact 
not all aspects of a scene have equally high demands on rendering complexity — some parts of a 
scene can easily be rendered in hardware, while others absolutely require software. mental ray 
3.3 is designed to permit this arbitrary combination of hardware and software rendering. 


Chapter 2 


Scene Description Language 


The mental images scene description language allows reading a scene from an ASCII or binary file 
called the .mi file. It contains a list of commands and scene entities. Commands are instructions 
that set options such as verbosity or external shaders to be linked. Scene entities describe 
geometrical objects and shaders and other components. Animations are rendered by setting up 
the first frame and rendering it, followed by scene modifications and another render command 
for every successive frame. These scene modifications are called incremental changes. 


This book describes version 2 of the .mi format, abbreviated as .mi2. Although mental ray 2.x 
and 3.x still support the frame-based scene definition method supported by version 1.x of mental 
ray, this is not recommended for future designs and not described here. Both versions of the 
format can easily be distinguished: .mil files contain frame statements, while .mi2 files contain 
instance statements. The recommended file extension is .mi regardless of the version. 


This section discusses the parts that make up an .mi file. A less formal syntax is used for the 
syntax description: a bar “|” denotes alternatives, items enclosed in tall square brackets “[ ]” are 
optional, and the ellipsis “...” denotes omission, as in “zero or more repetitions of the preceding 
construct.” Literal text is set in teletype, while variable metasymbols are set in italics. All other 
punctuation characters are literals. Strings are quoted with double quotes; this includes all names. 
mental ray permits strings containing literal double quotes if they are prefixed with a backslash. 
Names, such as material, light, or object names, need not be quoted, but it is highly recommended 
to avoid conflicts with reserved words’, and to allow non-alphabetic characters. Without quotes, 
only lowercase and uppercase letters, underscores, and digits may be used; a digit may not be the 


first character of an unquoted name. No such restrictions apply to quoted names. 


Integers are distinguished from floating-point numbers by appending the suffix int, as in degree int. 


<9 ”» 


Integers are an optional “+” or “—” sign followed by a sequence of digits “O” through “9”. 
Floating-point numbers follow the same rules, but may optionally contain a decimal point “.” 
and an optional exponent. If the number begins with a decimal point, a leading zero is assumed. 
Exponential notation has the form xem, which is interpreted as 7-10”. Strings can be distinguished 


from numbers because the grammar always requires them to be enclosed in double quotes. 


Future versions may reserve more words than described here. 
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The “#” character introduces comments, unless quoted, except between $code and $end code. 
Comments extend to the end of the line. 


Unquoted whitespace acts as a separator but is otherwise ignored. Line breaks and indentation 
have no syntactical relevance, except where otherwise noted (commands beginning with a dollar 
sign, for example, must appear at the beginning of the line). 


By convention, the first line of any .mi file should begin with the three characters #mi, followed 
by a blank (not a tab), followed by the partial or full version number of the earliest required 
mental ray version number. For the syntax described in this book this is 3.1.1, 3.2.1, 3.3.1, or 
3.4.1. This comment serves as a “magic number” that helps interactive programs or utilities like 
file to decide whether this is a .mi file or something else. It is not parsed by mental ray itself. 


2.1 Shader Declarations 


Shaders are procedural elements that are implemented in C or C++. They are typically, but not 
necessarily, precompiled and stored in shared libraries. They are linked by mental ray at runtime 
and perform a variety of functions, such as determining the surface characteristics of an object. 
The term “shader” originally referred to “surface shading” (color and illumination computation) 
but has expanded and now refers to any custom function, regardless of its use. 


All shading functions linked with a code or link statement, and all shading functions built into 
mental ray, must be declared. When called, shaders accept a pointer to an arbitrary parameter 
structure as their third argument, and mental ray must know the structure declaration in order 
to put together the parameter block according to C/C++ structure layout conventions. Usually, 
declarations are included from a separate file using the $include statement. For a detailed 
description of shader declarations, see the chapter on writing shaders. 


A declaration is a top-level statement that informs mental ray about the shader name (which 
is identical to the C/C++ function name), the return type, and the types and names of all the 
parameters. Certain options can also be specified. 


declare shader 
[type] "shader name" ( 
type "parameter_name" [ default] , 
type "parameter_name", [ default? , 


type "“parameter_name" [ default] , 


[ version versionjny | 
[ apply shader_type_list | 
[ options | 

end declare 


It is recommended that shader_name and parameter_name are enclosed in double quotes to 
disambiguate them from reserved keywords and to allow special characters such as punctuation 
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marks. Note that old-style declarations of the form 


declare [type] "shader name" (...) 


are also still supported for backwards compatibility, but they should not be used because they 
do not support versioning, apply masks, and options. The optional (but highly recommended) 
version is an arbitrary integer that identifies the shader version. The default is 0. See the discussion 
of shader versioning in section 3.7. If the shader has no parameters, the parameter list between 
the parentheses is left empty. 


mental ray 3.3 and higher support defaults for numerical parameters. They are specified by the 
optional default clause following the type and name. It consists of the keyword default followed 
by one (boolean, integer, scalar), three (vector, color), four (color), or sixteen (transform) values. 


This example: 
color "ambience" default i O 0, 


declares a color parameter named "ambience" with a red default RGB color. Whenever a shader is 
derived from this declaration, the ambience parameter will be red unless changed in the definition. 
The example specifies only RGB, so the alpha component defaults to 0. To make it default to 1.0, 
a value of 1 needs to be inserted before the comma. Parameters that have no explicit default clause 
are initialized with null values. It is not possible to specify defaults for non-numerical parameters 
and array members. 


2.1.1 Parameter Types 


The declaration gives the type and name of the shader to declare, which is the name of the C 
function and the name used when the shader is called, followed by a list of parameters with 
types. Names are normally quoted to disambiguate them from keywords reserved by mental ray. 
Commas separate parameter declarations. The following types are supported: 


boolean A boolean is either true or false. Possible values are true and false, 
or their synonyms on and off, 


integer Integers are numbers without decimal point in the range —2°' .. .2°! — 
i 
scalar Scalars are floating-point numbers, defined as an optional minus sign, 


a sequence of digits containing an optional decimal point at any place, 
followed by an optional decimal exponent. A decimal exponent is the 
letter e or E followed by a positive or negative integer. Examples are 
1 0s bend «> L oR4, OF -4.0876.. 


vector A vector is a sequence of three scalars as defined above, describing the 
x, y, and z components of the vector. 
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transform 


color 


shader 


colortexture 


scalar texture 


vector texture 


light 


string 


data 
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A transformation is a sequence of 16 scalars describing a 4 x 4 matrix, 
with the translation in the last row. The data structure consists of an 
array of 16 miScalars in row-major order. Many shaders check the 
last scalar and ignore the matrix if it is 0. In most cases the last scalar 
of a valid matrix is 1, and always nonzero. 


A color is a sequence of three or four scalars as defined above, 
describing the red, blue, green, and alpha components of the color, 
in this order. If alpha is omitted, it defaults to 0.0. 


Shader names defined with the shader statement (not to be confused 
with the shader declaration statement) can be passed to other shaders 
that have parameters of this type. The shader receives a tag that it can 
call using m1_call_shader and similar shader interface functions. 


Color textures name a texture as defined by a color texture 
statement in the .mi file. The color texture statement names either 
a texture file, or a texture shader followed by a user parameter list. 
Note that a color texture does not name the texture shader directly. 
When a color texture is evaluated, it returns an RGBA color. 


Scalar textures are equivalent to color textures, except that they name 
a scalar texture statement in the .mi file. When a scalar texture 1s 
evaluated, it returns a scalar (a single floating-point number). This is 
most often used to apply a texture map to a scalar material parameter 
such as transparency. 


Vector textures are another variation. They name a vector texture 
statement in the .mi file, which returns a vector when evaluated. Bump 
map bases on materials are typical applications for vector textures. 
Vector textures are rarely used. 


Lights specify a light instance as defined by an instance statement 
in the .mi file, which in turn names a light. Despite the name, shader 
parameters of type light do not name the light directly because only 
the light’s instance provides the necessary position and orientation 
information. Like textures, light parameters do not name light shaders 
directly. 


Strings are quoted character strings of arbitrary length. The data type 
is a tag that can be converted by the shader to a character pointer using 
the mi_db_access and mi_db_unpin shader interface functions. 


Data parameters reference a user data block, holding arbitrary 
structured or unstructured data of any kind. User data is useful for 
large amounts of shared scene data. Shaders access it much like strings. 
See section 2.7.6 for details. 
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lightprofile>! Light profiles such as IES and Eulumdat are physical lamp description 
files supplied by lamp vendors. They can be used by shaders to 
determine the accurate amount of light emitted in a given direction. 
See section 2.7.7 for details. 


geometry Geometry references objects, groups, or instances. They are allowed 
for all types of shaders but are primarily useful for geometry shaders, 
which can introduce geometric scene entities. Geometry shaders have 
a different shader API than other shaders. They are described in 
chapter 4.2. Shaders and phenomena whose return type is geometry 
can be used in instance definition statements (see page 169). 


material primarily useful in phenomenon definitions, which may contain 
materials in addition to shaders. Shaders and phenomena whose return 
type is material can be used in material definition statements (see 
page 114). 


gtrwct 1 ava 5 Structures define sub-lists of parameters. This is normally used to 
build arrays of structures, for example to declare an array of textures, 
each of which comes with a blending factor and other sub-parameters. 
The ellipsis ... stands for another (non-empty) comma-separated 
sequence of type/parameter_name pairs. 


array type Arrays are different from all other types in that they are not named. 
The array keyword is a prefix to any of the above types that turns 
a single value into a one-dimensional array of values. For example, 
array scalar "terms" declares a parameter named terms that is an 
array of scalars. The number of elements in the array size is dynamic 
and unlimited. Arrays of arrays are not supported. 


When choosing names, avoid periods and double colons, which have a special meaning when 
accessing interface parameters in phenomenon subshaders. 


The return type of the shader must either be a simple type (any type except struct or array), 
or an unnamed struct containing only simple types. Unnamed means that there is no name 
between the struct keyword and the opening brace. This allows a shader to return multiple 
result values. 


Note that mental ray 3.0 requires that contour store shaders are correctly defined with all return 
parameters, typically an unnamed struct. mental ray will use the size of the declared return 
parameters to reserve enough space for the contour store shader to store into. mental ray 2.1 
basically ignored the declared return parameters, and got the return size from the shader itself. 
mental ray 3.0 will print an error messages if the return parameters are undeclared, but an incorrect 
declaration will cause memory trouble. 
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2.1.2 Shader Apply Flags 


The apply statement allows specification of possible uses for the shader. The shader_type_list 
consists of a comma-separated list of one or more of the following keywords: 


shader application 


lens lens shader in a camera 

material material shader in a material 

light light shader 

shadow shadow shader in a material 

environment | environment shader in a material or camera 
volume volume shader in a material or camera 
texture texture shader 


photon photon shader in a material 
geometry geometry shader 

displace displacement shader in a material 
lightmap lightmap shader in a material 
emitter photon emitter shader in a light 
output output shader in a camera 

state state shader in options 


If the apply statement is missing, the applicability of a shader is unknown. This will commonly 
be the case for base shaders, for example, which can be used for any purpose. Apply lists help 
user interfaces to categorize shaders. mental ray performs no checks to make sure that shaders 
are used only in legal contexts, and in fact ignores the apply list completely. 


2.1.3 Declaration Options 


Declarations of shaders (and phenomena, see page 70) allow a number of options to be specified 
in the declaration block. These options specify requirements of the shader or phenomenon, 
specifying conditions that must be met before the shader or phenomenon can run correctly, or 
information about the shader that tells mental ray how to call it. They should be used only if 
it is impossible for the shader to do its job without this option, but not to second-guess the 
user, assuming that if this shader is used, then the user “probably” wants this option. Shader 
requirements take away control from the user and should be used with care. Before rendering, 
mental ray collects the requirements of all shaders defined in the scene, checks for conflicts, and 
adjusts global options and camera parameters to suit the shaders. Shaders should not assume that 
an option specified in the declaration has an effect because mental ray may choose to ignore it if 
there is a conflict with another declaration. 


For example, if a shader specifies that it can operate only if ray tracing is enabled (a common case 
for lens shaders), it should specify the trace on option to tell mental ray to enable ray tracing 
even if no ray tracing was specified in the global options statement. 
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Here is the complete list of available options. If an option is not present, the default is “don’t care” 
unless otherwise noted. If specified, these options are equivalent to the corresponding options 
given in the options top-level statement; refer to the description of option blocks for more 
details on the operation of these options. 


scanline on|off 


trace on|off 


shadow off 


shadow on 


shadow sort 


shadow segments 


face front |back|both 


derivative [1] [2] 


object space 


camera Space 


volume level;,, 


The scanline rendering algorithm must be turned on or off, 
respectively. 


Ray tracing must be turned on or off. For example, lens shaders 
that modify the ray direction should set this to on. 


Shadows must be turned off for this shader to function. 


Shadowing must be enabled, either regular, sorted, or seg- 
mented. 


Shadowing must be enabled, either sorted or segmented. 
Regular is not sufficient. 


Segmented shadows must be enabled. Regular or sorted 
shadows are not sufficient. 


Intersection testing should consider front-facing, back-facing, 
or both front-facing and back-facing geometry, respectively. 
For example, a surface is visible if the incoming ray direction 1s 
opposite to the normal vector of the surface, and the face mode 
is either front or both but not back. 


The object that this shader or phenomenon is attached to (by 
being named in its material, for example) must have first or 
second derivatives, respectively, or both. This option has an 
effect only on free-form surface geometry because mental ray 
cannot compute derivatives for polygons. 


The shader functions only if all geometry is defined in object 
coordinates. 


The shader functions only if all geometry is defined in camera 
space. 


The volume level?* defines the “density” behavior of volume 
shaders. If autovolume mode is enabled in the options block, 
mental ray keeps track of which volumes a ray is in. If the 
current point is in multiple volumes, equal volume levels mix, 
and higher levels displace lower volumes. For example, if the 
point is in four volumes A, B, C, and D, with volume shaders 
defining levels 3, 2, 3, and 1, respectively, both the volume 
shaders A and C will be called because they displace B and D. 
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See page 253 for more information about autovolume-enabled 
volume shaders. 


2.2 Shader Definitions 


After a shader has been declared, it can be used in a definition. While a shader is made known to 
mental ray using a declaration only once, it may be used any number of times. Each use is called a 
definition. A definition supplies numerical or other values for shader parameters, and is attached 
to some other scene element. 


In this book, shader definitions will be used in many places, denoted by the shader meta symbol. 
A shader is defined as a shading function name followed by parameters: 


"shader name" (parameters) 


This sequence can be inserted for every instance of shader in the rest of this book. (There are other 
forms, lists and named references, that can also be used in place of shader. They are described 
later.) 


The shader name must have been previously declared with a declare command; see above. 
Normally shader libraries containing compiled C/C++ shaders come with a $include file that 
contains all declarations for the shaders in the library. The library itself is typically linked into 
mental ray with alink command. There are usually many shader references for every declaration, 
each with a unique set of parameters. The syntax of shader calls is described in the chapter on 
shaders; they are basically acomma-separated sequence of quoted parameter names, each followed 
by a parameter value. 


The parenthesized parameters list is a comma-separated list of shader parameter assignments that 
have one of the following three forms: 


"parameter_name" value 
"parameter_ name" = "shader_name" 
"parameter name" = interface "ifname" 


The first form assigns a constant value to the parameter. The format of constant values depends 
on the parameter type: 
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boolean 


integer 
scalar 
vector 
transform 
color 


string 


data 

shader 

color texture 
scalar texture 
vector texture 
light 

material 
geometry 


true 
false 
value nt 
value 
xz 


A400 401 402 403 410 411 412 413 420 421 422 423 430 431 432 433 


red green blue 

red green blue alpha 
"string" 

"data_name" 

" shader_name" 
"texture name" 
"texture name" 
"texture name" 
"light_instance_ name" 
"material name" 


" object_group_or_instance_name" 
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struct {parameters } 
array [comma-separated value list] 


Integer values must be signed 32-bit values. All other numerical values are floating-point numbers 
that may contain a decimal point and/or a decimal exponent introduced by the letter e, as 
in 1.6e-27. The shader_name must be the name of a named shader from a preceding shader 
statement; the texture_name must be the name of a previously defined color texture, scalar 
texture, or vector texture statement, respectively. 


The special value keyword null can be used to replace any number, symbol, string, data, true, 
or false. It stores the numerical value 0 in the parameter. Its main purpose is to create “holes” 
in arrays by listing nulls between the square brackets. 


The two non-constant forms of parameter assignment are explained later. 
The above shader definition form is also called an anonymous shader because the shader 


name/parameter pair is formed on the fly and used in place. Sometimes it is useful to give a 
name to a shader/parameters pair using a shader statement and use it more than once: 


shader "named_shader" 
"shader name" (parameters) 


Such pairs are called named shaders. After the pair was set up with a shader statement, it can be 
used in any place where a shader can be used, as an alternative to the anonymous shader statement 
listed above: 


= "named_shader" 
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This is especially useful if the same shader/parameters pair is used in many different places in 
the scene, and it changes for every frame. Since shader statements allow incremental changes, 
an incremental change to a named shader affects all places that reference it (with the exception 
of displacement shaders — once an object is tessellated it remains unchanged until explicitly 
modified). Without named shaders it would be necessary to incrementally change every scene 
element containing the shader. 


2.3 Shader Lists 


In most constructs accepting a shader, shader lists are also accepted. A shader list consists of one 
or more shader items like one of the two above in sequence. For example, suppose that a named 
shader has been defined with the following command: 


shader "named_shader2" "shader2" (parameters) 


then the following shader list can be written: 


"shader1" (parameters) 
= "named_shader2" 
"shader3" (parameters) 


This shader list will call three shaders in sequence, shader1, shader2, and shader3, in this order, 
each with its parameters. All shaders get the same resu/t pointer, so each operates on the results of 
the previous. A shader list like this can be substituted for all instances of the meta symbol shader_ 
list in this chapter. 


Shader lists are maintained by storing a link to the next shader in the previous shader. In the above 
example, the anonymous shader shader/ contains a link to name_shader2, which contains a link 
to shader3. This means that once this list is set up, any reference to named_shader2 will implicitly 
also call shader3 because the link in named_shader2 will remain in the shader until changed in 
another shader list. This can have surprising results. This is not a problem in anonymous shaders 
because, not having a name, they cannot be referenced in more than one place. In general it is a 
good idea to avoid putting named shaders in shader lists. 


2.4 Shader Graphs 


Instead of assigning a constant value to a parameter in a shader definition, it is possible to assign 
a shader: 
"parameter_name" = "shadername" 


For parameters assigned in this way, no value is stored in the shader definition. It is obtained 
by calling shader_name at runtime. For example, if the ambient parameter of a material shader 
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has the constant value 1 0 0, it is always red, but if another shader is assigned to it that other 
shader is called when the material shader asks for the value using the mz_eval function or one of 
its derivatives. The other shader could be a texture shader, for example, resulting in a textured 
ambient value. 


The return type of the assigned shader must agree with the parameter type. If the return type of 
the assigned shader is struct, it is possible to select a structure member by appending a period 
and the name of the struct member to the shader name. Consider the following assignment: 


declare shader 
color "phong" (color "ambient", 
color "diffuse", 
color "specular") 
version 1 
end declare 


declare shader 
strict tcolor “a", color "b"} 
"texture" (color texture "picture") 
version 1 
end declare 


color texture "fluffy" "/tmp/image.rgb" 


shader "map" "texture" ( 
"picture" “Pilurry™) 


shader "mtlsh" "phong" ( 
"ambient" 0,3 0.9 @.3, 
"diffuse" = "map.a", 
"specular" = "map.b") 


This defines a material shader that does not support texturing in any way because it has no 
parameters of type shader or color texture. Yet, shader assignments allow its diffuse and 
specular components to be textured without the phong shader being aware of it. Whenever phong 
accesses its ambient parameter value by calling mi_eval, it gets a constant color 0.3 0.3 0.3. When 
it accesses its diffuse or specular color, a call to the named shader map results (which actually calls 
shader texture), whose result is then returned to the phong shader. 


In this example, the map shader returns two colors a and b, which are selected in the shader 
assignment by appending .a and .b to map. (For this reason periods should be avoided in 
parameter names.) If the shader had returned only a single color, only "map" would have been 
assigned, without appending a period and a structure member name. 


In the example, map is assigned twice. Obviously it is not desirable to actually call it twice, because 
the first call will already have set both its a and b return values. After the first call from a shader, 
mental ray caches the return value to avoid further calls. As soon as the shader phong returns, the 
cache is discarded to ensure that the next call to phong, most likely with a different state, calls 
map instead of using a stale cache. 
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Note that shaders that support shader graphs must use the mz_eval function to access their 
parameters. This was done to ensure that only those assigned shaders whose values are actually 
used are evaluated. For example, a material shader that has two color parameters, one for the 
front and one for the back side of the surface, will access only one of its parameters by using mz_ 
eval only once. 


To see how the phong shader is implemented as a C shader, see section 3.6. 


The advantage of shader assignment is that it is not necessary to write shaders to accept procedural 
values. Without shader assignments, a simple Phong material shader would need parameters of 
type shader or color texture in addition to the standard ambient, diffuse, and specular parameters. 
Shader assignment allows writing small, reusable “base shaders” that can be easily combined into 
powerful shader graphs, instead of writing large monolithic shaders that are hard to modify and 
inflexible to use. 


The third form of parameter assigning using the interface keyword is available only inside 
phenomena, which will be discussed next. 


2.5 Phenomena 


This section only describes the representation of phenomena in the .mi language. The declaration 
of a phenomenon is very similar to the declaration of a shader, except that the keyword shader is 
replaced with phenomenon, and the addition of new optional statements in the declaration block: 


declare phenomenon 
[type] "phenomenon_name" ( 
type "parameter_name" , 
type "parametername", 


type "parameter_name" 


[ version version in | 
[ shader "name"... | 
[material "zame"...end material | 
[ light "zame"...end light | 
[instance "name" ...end instance | 
[ roots | 
[ options | 

end declare 


For a description of version, shader, material, light, and instance definitions, see the corresponding 
section above; the syntax is identical to the one described there. The order of shaders, materials, 
lights, and instances is arbitrary, as long as a name is not used before it was defined. The options are 
identical to the options described in the shader declaration section above. The roots are described 
below. 
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The phenomenon phenomenon_name declared with this statement is available for the definition 
of shaders just like a shader declared with adeclare shader statement. Named and anonymous 
shader definitions can be derived from either type of declaration. Phenomena were designed to 
extend the concept of shaders, not to replace it. 


2.5.1 Phenomenon Interface Parameters 


Phenomena, like shaders, have parameters. In the phenomenon case they are called “interface 
parameters” because they form the gateway between the rest of the scene and the internal 
implementation of the phenomenon. Interface parameters are what makes the phenomenon 
look like a simple shader to the named and anonymous shader definitions. Phenomena are 
implemented in terms of subshader nodes, each with their own parameters. Subshader parameters 
can be assigned from the interface using an assignment of the following form: 


"parameter_name" = interface "ifname" 


This looks similar to the shader assignments described above, but when the shader calls mi_eval 
on a parameter assigned to the interface of the phenomenon it is defined in, no shader is called 
but the value is obtained from the phenomenon interface. For example: 


declare shader 
color "phong" (color "ambient", 
color "diitiuse", 
color "specular") 
version 1 
end declare 


declare phenomenon 
color "phong_phen" (color "col") 
version 1 


shader "sub" "phong" ( 
"ambient" 0.0 030 O23; 
"diffuse" = interface "col", 
"specular" 1.0 1.0 1.0) 


root = "sub" 
end declare 


shader "mtlsh" "phong_phen" ( 
"CoOL" 1.0 0.5 0.0) 


For the shader definition, the phenomenon phong_phen looks like a shader with a single color 
parameter col. Internally, it contains the definition of a simple shader sub with three parameters, 
two of which have constant values and one which takes its value from the interface. When the 
shader definition mtlsh is called from a material or elsewhere in the scene, it calls the phenomenon 
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phong_phen with the value 1.0 0.5 0.0 for the interface parameter col. This value is propagated to 
the diffuse parameter of the shader sub during evaluation of the phenomenon. 


It is important to distinguish parameter values, such as 1.0 1.0 1.0 for specular, from shader 
assignments, which begin with an “=” sign. In particular, consider the shader parameter type 
shader: if a shader name is given as the value without “=” sign, the named shader will be returned 
but not called by mz_eval. With an “=” sign, m1_eval will call the shader and expect it to return 
another shader (so its return value must have type shader) which is then returned by mzi_eval. 
The latter involves an indirection, and is not often used for parameters of type shader. This is a 


common mistake, and return type mismatches will result in mental ray warning messages. 


When calling a phenomenon, all its parameters must pass through the interface. The shader sub 
and everything else defined inside the phenomenon block is visible only inside the phenomenon, 
and no names defined outside the phenomenon are visible to definitions inside the phenomenon. 
The interface is the only connection point between the inner and outer world. This encapsulation 
ensures the integrity and completeness of phenomena independently of the scene they are used 
in. 


Phenomena may also contain material, light, and instance definitions in addition to shader 
definitions. 


By convention, anonymous shader definitions should not be used in phenomenon declarations. 
There is no functional disadvantage in using anonymous shader definitions but it makes life 
difficult for graphical phenomenon editing tools like mental ray’ Phenomenon Creator™, which 
uses shader names to label the icons and boxes that represent subshaders in its graph and browser 
views. 


The return type of a phenomenon may be any type that is a valid return type for a shader. 


2.5.2 Phenomenon Roots 


The above example also illustrates a new option allowed in phenomenon but not shader 
definitions, the phenomenon root. There are several types of root statements: 


root shader 

root material "material name" 

geometry shader 

volume shader 

environment shader 

lens shader 

output shader 

output ["type"] "format" [opt] "filename" 
contour store shader 


contour contrast shader 


volume priority priorityint 
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lens priority priority int 
output priority  priorityin 


All of these except one of the first two are optional. The first root statement specifies the 
primary root shader of a phenomenon that is called when the phenomenon is called. In the above 
example, the mt/sh shader, when called, calls the phenomenon phong_phen, which immediately 
calls its subshader sub because sub is specified in its root statement. 


The root material variant creates a material phenomenon. This type of phenomenon must be 
declared with the return type material. It is instanced normally with a shader statement, which 
provides the interface parameter values. The resulting shader is different from regular shaders; 
its name can be used everywhere where a material name is valid. A regular phenomenon that 
does not have type material and no root material statement, when instanced using a shader 
statement, becomes a shader, not a material. Material phenomena should be used instead of regular 
phenomena if the phenomenon depends on not only assigning a single shader, such as a material 
shader, but other material components such as shadow shader, photon shader, volume shader etc. 
as well. See page 116 for an example of a material phenomenon. 


In addition to the main root statement, other roots may be defined that reference shaders of 
other types: 


geometry The geometry shader or shader list is evaluated before rendering starts. 
This allows the phenomenon to introduce procedural geometry into 
the scene. For example, a light beam phenomenon might install a 
transparent cone in the scene that bounds the volume effect. 


volume The volume shader or shader list is added to the camera before 
rendering starts. This allows the phenomenon to specify a global 
atmosphere that should be installed if the phenomenon is defined. 


environment The environment shader or shader list is added to the camera before 
rendering starts. This allows the phenomenon to specify a global 
environment shader that should be installed if the phenomenon is 
defined. Environment shaders are called when a ray does not intersect 
any object. 


lens This root is doing the same thing for lens shaders that should be added 
to the camera before rendering starts. 


output The list of output shaders and file output statement is added to the 
camera before rendering starts. This allows the phenomenon to specify 
output shaders that should be installed if the phenomenon is defined. 
For example, the phenomenon might write a label frame buffer whose 
values are picked up by the output shader after rendering completes. 


contour store The contour store shader is used for contour rendering. 


contour contrast The contour contrast shader is used for contour rendering. 
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Note that during rendering, only root (or root material in the material phenomenon case) 
has any significance because the others have been removed and added to the camera or the scene 
before rendering started. After rendering and output shading completes, all these changes are 
undone. Note that if the phenomenon is defined several times (using multiple shader statements 
or anonymous shader definitions that reference it), the roots other than the main root are added 


to the scene more than once’. 


The shader priority statements provide control over the placing of the specified shaders or shader 
lists in the corresponding shader list in the camera. Shaders with greater priority numbers are 
appended to shaders with smaller priority numbers, and hence execute later. Shaders with no 
priority number have priority 0, so they get executed before shaders with positive priority 
numbers. The shaders defined in the camera always have priority 0. 


2.6 Commands 


Commands are instructions to mental ray that are executed the moment they are read from the 
input scene file. They do not add elements to the scene database. Since the scene file is only read 
by the master host in a network configuration, commands are never seen by slave hosts. 


$include "filename" 
$include <filename> 


The $ sign must appear in the first column of the line. The named file is included (pasted into) 
the .mi file in place of the $include statement. Includes can be nested. The main purpose is to 
include declarations (see below), but materials, light sources, even objects can be included. The 
only place where $include cannot be used is between $code and $end code; use the standard C 
#include statement there. The included file is read on the master host only. If the filename is 
enclosed in angle brackets, the standard include path is prepended, by default /usr/include. 
The standard path can be changed with the -I command-line option. 


namespace "name" 
end namespace 


°° A namespace bracket can enclose any number of toplevel element definitions. Any toplevel 
element name defined and used in this bracket will be prefixed with “name: :”. For example, a 
material named "mt1" defined in the bracket will be named "name: :mt1". Inside the bracket it 
can be referenced as "mt1", but outside the bracket the full "name: :mt1" name must be used. 
Inside the bracket, global toplevel elements outside the bracket can be referenced by prefixing the 
name with ::,asin"::mt1". Namespaces are useful to define subscenes that should not interfere 
with other subscenes or the main scene. 


*Shaders attached directly or indirectly to the output, contour store, and contour contrast roots may not use 
interface or shader parameter assignments. 
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Note that all geometry created by a geometry shader is implicitly defined in a namespace with a 
unique namespace name that is automatically generated by mental ray. This is how two geometry 
shaders that both create toplevel elements with the same name avoid interfering with each other. 


Note that the -echo command-line option does not reproduce the namespace statements, but 
instead generates the full : : names. 


[min] version "string" 
max version "string" 


This command informs mental ray that this .mi file requires the given mental ray version. min 
means “at least” and max means “at most”. Version strings consist of numbers separated with dots, 
such as "1.2.3.4". The string can underspecify the version, as in "2.1". Missing numbers are 
implicitly assumed to be 0 so "2.1" becomes "2.1.0.0". Each number, beginning with the first, 
is checked in turn. If the number in the string is greater (min) or less than (max) than the version 
number built into mental ray, an error message is printed and mental ray aborts; otherwise the 
next number is considered. If all given numbers pass the test, mental ray continues. 


File version numbers are especially useful for declaration files, such as base.mi in the standard 
distribution. They are mainly useful for making sure that certain mental ray features and scene 
file syntax are present. For example, a scene file using demand-loaded placeholder objects may 
specify min version 3.0 because that feature was introduced in mental ray 3.0, and would cause 
a syntax error in mental ray 2.x. Shaders have their own version numbers in declarations that are 
independent of mental ray version numbers. 


verbose onloff |/evel,,,, 


This command controls verbose messages. There are seven levels: fatal errors (0), errors (1), 
warnings (2), progress reports (3), informational messages (4), debugging messages (5), and 
verbose debugging messages (6). All message categories numerically less than /evel are printed. 
Verbose off is equivalent to level 2 (fatal errors and errors only); verbose on is equivalent to 
level 5 (everything except debugging messages). Verbose messages can slow down mental ray 
while parsing, especially on systems with poor I/O systems such as Windows NT because of 
slow scrolling. Verbose level 7 should generally be avoided; it prints information that is really 
only useful for mental images. The verbose command can be overridden with the -verbose 
command-line option. 


echo "message" 
The named message, which must be enclosed in double quotes, is printed to stdout. The echo 


command is executed synchronously during parsing the .mi file. Echoing requires verbosity level 


4 or higher. 
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call shader_list[, "camera_inst" "options" | 


The given shader is called immediately, and parsing stops until the shader completes. Since the 
shader is called during parsing and not during tessellation or rendering, the entire state passed 
to the shader is filled with nulls, which limits what the shader can do (it cannot cast rays, for 
example). If the name of a camera instance element and the name of an options element is given, 
state — options and state — camera are set up for the shader. The return value is ignored. The call 
statement is intended for early initialization of shader packages, or even to start interactive front- 
end packages from inside a standalone mental ray. Shader init and exit functions are not called 
by the call statement. For shader initialization, shader init functions are more useful because 
they are called with a full state, and only if the corresponding shader is actually needed. Call 
statements are rarely used. 


touch "element_name" 


>> Mark the named toplevel scene element for re-evaluation. This is useful to mark objects for 
retessellation when a displacement shader or one of its direct or indirect subshaders changes 
(mental ray cannot discover this by itself), or when the contents of a texture file have changed on 


disk and need to be reloaded. 


system "shell_command" 


This command starts a shell, which executes the named shell.command. The shell command 
string must be enclosed in double quotes. The full shell scripting command syntax is available, 
including pipes, redirections, control structures, and environment variables. mental ray waits 
until the shell command has completed; this can be defeated by ending the command with a 
shell & command. The system command is executed while parsing, not during rendering. Its main 
purpose is writing finished pictures to an output device such as a film recorder. Shell commands 
are operating-system dependent and are much less useful on Windows NT because NT shells are 
severely limited. Note that shell commands, like shaders, are executed with the privilege of the 
user running mental ray. 


delete "element_name" 


Delete a named scene element, such as objects, materials, lights, textures, instances, and instance 
groups. Declarations cannot be deleted. It is possible to delete an element and recreate it with 
the same name, but this breaks all links. For example, if a light is created and then an instance 
is created for it, naming the light, the link between instance and light is broken when the light 
is deleted and recreated. The instance retains a dangling link that will cause havoc during later 
processing. The delete command should be used only for entities that disappear permanently. 
All instances and instance groups that contain the name must be updated before the name is 


deleted. 


Instead of deleting and recreating an element, an incremental change should be used by prefixing 
the element definition with the incremental modifier. This has the additional advantage that 
the element retains all contents that are not modified during the new incremental definition. 
For example, an incremental change to a camera containing nothing but a new frame number 
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specification will leave the camera unchanged except for the frame number. As an exception, 
objects and instgroups are cleared first because merging 1s not generally useful in these cases. 


touch "element_name" 
>-2Mark the element as modified, as if an empty incremental change had been performed. This is 
useful on objects, which normally do not get retessellated in future frames unless they are edited 
in some way. For example, mental ray does not know whether a displacement shader would 
produce different results in the next frame, and would keep on using the old tessellation, unless 
the object was explicitly touched. Touching invalidates the existing tessellation. 


debug "mode" ["arg"] 


Print debug information to the stderr. The verbosity (-verbose) must be set to 4 or higher. Some 
modes print information ona specific database element arg. The following modes are supported: 


sym 

sym global 
sym declare 
sym variable 
sym hardware 
registry 

mem summary 
db statistics 
db summary 

db dump 

job statistics 
img verbose 
scene check 
scene dump 
scene alldump 
echo 


print all symbol tables 

print the main global symbol table 

print all declaration symbols 

print all variables from the set command 
print all hardware shaders’ 

print all registry command entries 

print memory usage summary 

print scene database tag usage statistics 
print scene database tags by module and type 
print all tags in the scene database 

print summary of executed jobs 

turn on debugging for loaded image files 
check database consistency of tag 

brief listing of tag hierarchy 

verbose listing of tag hierarchy 

echo a tag, like -echo 


render "rootinstgroupname" "camerainstname" "“optionsname" 


This statement renders the scene. The name of an options element, a camera instance element 
(which must also have been attached to the root instance group), and the root instance group 
must be given. 
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2.6.1 Variables and the Registry 


set "name" ["value"] 


Assign the value value to the variable name. Variables are not used by mental ray but provide 
a general syntax for passing parameters from translators to interactive programs that read scene 
files without actually parsing any geometric data. For example, translators can store the translator 
version and name, source scene name, frame range, and other useful information in variables. 


registry "name" ["value"| 
[value "value"] 
[link "library.so/dll" | 
[code "sourcefile.c" | 
[mi "scenefile.mi" | 
[spdl "scenefile.spdl" | 
[echo "string" | 


[system "shell command"] 
end registry 


Create a mental ray registry entry. The registry is similar to the symbol table created with the set 
command, but is actively accessed and evaluated by mental ray. All file paths on disk go through 
registry substitution, and conditionals use registry keys as well. Any string can be used as a name, 
but a few that begin with _MI_REG_ have special meanings: 


_MI_REG_INCLUDE an include path where files included by $include commands are 
found, in addition to paths set with the -I command-line option. 


_MI_REG_LIBRARY an include path where shader libraries linked by link commands are 
found, in addition to paths set with the -L command-line option. 


-MI_REG_TEXTURE an include path where texture image files referenced by texture 
statements are found, in addition to paths set with the -T command- 
line option. 


-MI_-REG_LIGHTPROFILE an include path where light profile files referenced by lightprofile 
statements are found, in addition to paths set with the -lightprofile_ 
path command-line option. 


_MI_REG_SWAPDIR a directory to swap to, unless the -swap_dir command-line option 
has been specified. 
-MI_REG_SWAPLIMIT the number of megabytes to write to the swap directory, unless the 


-swap_limit command-line option has been specified. 


_MI_REG_FBDIR>* a directory where memory mapped frame buffers are stored, unless 
the -fb_dir command-line option has been specified. 
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The values must be specified in value statements. Effectively, this allows providing defaults that 
could otherwise only be specified on the command line. The optional statements other than 
value are used by the $lookup command; see below. Typically, registry commands are used in 
the rayrc startup file, usually stored in places like /usr/local/mi on Unix, or at the directory 
the MI_ROOT environment variable points to. 


$lookup "name" 


This command looks up a a registry name specified with a preceding registry command, and 
executes the statements found there: link loads a library; code compiles and links source code; 
mi reads a scene file like $include; spdl reads a scene file in Softimage SPDL syntax; echo prints 
a string to the console; and system executes a shell command. Lookup statements are useful as 
facility macros. For example, to make a set of features available to mental ray, a single lookup 
statement can load the library, load .mi declarations for it, print a message to the screen, etc. 


2.6.2 Shader Compilation and Linking 


code "filename" 


The named filename is interpreted as a C source file, ending with the extension “.c”, is compiled 
and linked into mental ray. From this point on, the shaders it defines are available in mental ray 
as shading functions. For example, if the source defines a C function myshader, with the usual 
three parameters result, state, and paras (see chapter 3 for details), the name myshader may be 
used in materials, lights, textures and so on as the quoted shader name. The command-line option 
-code provides an alternative way of compiling and linking C source. Multiple code commands 
are possible. This is intended mainly for debugging because linking precompiled shader libraries 
is much more efficient. Note that every shading function must also be declared; see section 2.1. 


Compiling C++ code requires that the shader function prototypes and any included mental ray 
headers such as shader .h are included in extern "C". It may also be necessary to switch the 
compiler using the -c_compiler and -c_linker command-line options. 


$code 
C source text 
$end code 


The $ signs must appear in column 1 of the line. This command also compiles and links C source 
code, but the code is read directly from the .mi file rather than from a separate source file. The C 
source text follows standard C syntax. In fact, it is written out to a temporary file, which is then 
compiled as if a code command had been used. Multiple $code commands are allowed. Note that 
every shading function must also be declared; see below. C++ requires the same steps as for the 
code command. 
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link "filename" 


Like the code command, the link command attaches external shaders to mental ray, which can 
then be used as shading functions. While the code command accepts “.c” files as filename, the 
link command expects either object files ending in “.o”, or dynamic shared object (DSO on Unix, 
DLL on Windows NT) files ending in “.so”. Object files are linked, while DSOs are just attached 
without any preprocessing. DSOs are the fastest way of attaching an external shader, and require 
no compilers or development options, which are sometimes sold separately by system vendors’. 
However, certain old systems do not support DSOs. The -link command-line option provides 
an alternative way of linking object files and DSOs. Any number of files can be linked. Note that 
every shading function must also be declared; see section 2.1. If Dynamical Shared Objects are to 
be linked on Unix machines, the LD_LIBRARY_PATH or LD_LIBRARYN32_PATH (SGI) environment 
variable must include the path of the DSO file to be linked; see section 3.1. 


2.6.3 Conditionals** 


Portions of the scene file can be excluded from consideration during parsing, depending on 
conditional statements that bracket the portions of the scene file to be excluded. The primary 
example for this is protecting included files from double inclusion. For example, a file x. 
included with $include might begin with the statements 


$ifndef "x_mi" 
set “x.mna" “truce” 


# normal contents of x.mi 


$endif 


The following conditional statements are supported: 


$ifdef "key" 

$ifndef "key" 

$ifeq "key" "constant" 
$ifneq "key" "constant" 
$else 

$elseifdef "key" 

$elseifeq "key" "constant" 
$endif 


The $ sign must be in the first column of the line. The usage always follows the pattern #f ... endif, 
or if ... else ... endif. Conditionals can be nested. As a convenience, an else can be concatenated 


>For system and development software requirements, see the Release and Installation Notes. 
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with another zf; in this case only one endif is needed because the concatenated forms do not 
require an endif of their own. 


There are two forms of if statements: those that check whether a key is present, and those that 
compare two strings. The key strings take one of two forms: 


e A string without curly braces. This is interpreted as the name of a variable that can be 
set with the set command. If the variable was set, it is said to be defined, and its value is 
the value from the set command. If there was no such set command, or a set command 
without a value, it is said to be undefined. 


e A string containing curly braces. This string goes through registry substitution, which 
will replace registry keys and environment references enclosed in curly braces with the 
appropriate values. If this results in a non-empty string, the value is said to be defined, and 
undefined otherwise. 


The constant strings take only the second form; variable lookups are not possible here. A constant 
without curly braces will be treated as a literal string, not a variable name. 


Note that conditionals can also be useful in rayrc startup files. For example, paths and all sorts of 
other platform-dependent setup keys can be made dependent on a single variable. For example: 


registry "{EXT}" value "so" end registry 
$ifeq "{EXT}" "so" 

echo "hello, penguin" 

$endif 


Conditionals can be used even in the middle of a statement, as long as the conditional is on its 
own line. (mental ray ignores whitespace and line breaks in statements.) This introduces a conflict 
where a conditional follows a set statement with only a single argument, which normally clears 
the named variable, and that same variable is used in the conditional: 


set "var" 
$ifdef "var" 


Is the variable being unset so the conditional should be false, or is the second argument of the 
set command inside the conditional? mental ray cannot know this. It assumes the latter, so the 
set statement is considered unfinished and has no effect on the conditional. 
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The conditional statements are: 


$ifdef "key" 


Proceed if key is defined, or skip to the matching $else or $endif otherwise. 


$ifndef "key" 


Proceed if key is not defined, or skip to the matching $else or $endif otherwise. 


$ifeq "key" "constant" 
Proceed if key evaluates to the same string as value, or skip to the matching $else or $endif 
otherwise. 

$ifneq "key" "constant" 
Proceed if key does not evaluate to the same string as value, or skip to the matching $else or 
$endif otherwise. 

$else 
Reverse the condition tested in the previous $ifx or $elseifx test, and proceed if we were 
skipping or skip if we were proceeding, until the next $endif. Only one $else is allowed per 
$ifx, and it must be last in any $elseifx chain. 

$elseifdef "key" 
A combination of $else and $ifdef. It does not need its own $endif. For example, $ifx ... 
$elseifx ... $elseifx ... $else ... $endif is legal. 

$elseifeq "key" "constant" 


Similarly, a combination of $else and $ifeq. 


$endif 


Finishes a conditional sequence that has started with $ifx. 
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A .mi file contains commands and scene entities in any order, with the restriction that an element 
must be defined before it can be referenced. All entities are named; all references are done by 
name. The following entities can be defined: 


options global options 
camera camera: output files, aperture, resolution, etc. 
material shading, shadows, volumes, environments, contour, etc. 


texture 


light 


object 

instanc 
instgro 
shader 
data 


procedural texture or texture image 
light 
polygonal or free-form surface geometry 
e places objects, lights, cameras, and groups in 3D space 
up | for grouping instances; the nodes of the scene DAG 
optional named shaders 
arbitrary user data 


lightprofile | light profile such as IES or Eulumdat?'! 


All of these can be 


defined at any place, as long as they are not nested (the definition of an 


element must be completed before the next element can be defined). All these entities can also 
be incrementally changed by introducing the definition with the incremental keyword, which 
tells mental ray to re-define an existing element instead of starting a new one. The contents of the 


existing element bec 


options 


camera 


texture 


material 


light 


ome the defaults for the new one. 


This element contains rendering options such as the shadow mode, tracing 
depth, sampling algorithm and its parameters, acceleration algorithm and its 
parameters, dithering and other modes. 


The camera is a description of the camera characteristics such as focal length 
and aperture that determine the field of view. 


Textures to apply 2D or 3D color, bump, transparency, displacement and 
other maps to objects. Textures are referenced by other shaders that include 
the texture in their color or other computation. Textures may appear verbatim 
in the file, or may be read from a texture file, or may be fully procedural, or 
a combination of these. 


Materials describe the surface properties of objects, volumic properties of 
the space enclosed by objects, transparent shadow casting, environment 
mapping, and displacement mapping, as well as a number of property flags. 


Lights illuminate objects and volumes. Lights are referenced in materials only 
(through the light instance), they are not applied directly to objects. All lights 
name a shading function; there are predefined shaders for points, spots, and 
directional lights, optionally in combination with various types of area light 
sources. 
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object 


instance 


instgroup 


shader 


data 


lightprofile 
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Objects describe the actual geometry. Objects may reference materials to 
determine the visual appearance of the surface. Various types of geometry 
descriptions are supported, such as polygonal objects and free-form surfaces. 
By default, all objects are defined in a local coordinate space (object space), 
usually with the origin at the center of the object. Options exist to switch to 
camera space instead. 


When an object, light, camera, or instance group is defined, it does not 
become part of the scene. It must be placed in 3D space with an instance, 
which contains a transformation matrix, inherited parameters, and several 
flags. It is possible to have more than one instance reference the same object, 
light, camera, or instance group; this is called “multiple instancing”. The 
instanced entity then appears several times in the final processed scene. It is 
possible to specify a “geometry shader” as the instanced item instead of an 
object. The “geometry shader” is expected to create a scene element which is 
defined in the local coordinate space of the instance. 


Instance groups are used to group instances so they can be instanced as a unit. 
Instance groups form the nodes of the scene DAG (Directed Acyclic Graph), 
which contains all entities used during processing. The instance group at the 
root of the DAG is called the “root instance group.” Since instance groups 
can themselves be instanced the scene DAG can be built with any number of 
levels and sub-DAGs, each with its own local coordinate space. 


Shaders are user-provided functions used for a variety of purposes. They 
are not normally named; they are defined where they are needed, like in 
a material. An unnamed shader is also called an “anonymous shader.” The 
shader statement allows giving a name to a shader; a named shader can be 
used in any place where an anonymous shader is expected by giving its name, 
introduced by an equals sign. 


User data blocks are independent named toplevel scene entities that hold 
structured or unstructured data of any kind. Structured data is declared 
much like shader parameters, while unstructured data is a raw byte stream 
with a fixed size. User data is useful for large amounts of shared scene data. 


Light profiles*:! such as IES or Eulumdat are files supplied by lamp vendors 
that describe the emission characteristics of physical lights. Light profile 
blocks can be defined in the scene file that reference the lamp vendor profile 
file, and passed to shaders as parameters of type lightprofile. Shaders can 
then look up the emission characteristics of the light. 


All scene entities are described in more detail in the following subsections. 


mental ray 3.2 allows forward references from groups to instances; and instances to groups, 
objects, lights, and cameras. This means that it is possible to write a group block that names 
an instance that does not yet exist, for example; mental ray will resolve the connection when 
rendering begins. In all cases not listed above, an element must exist before it is used. Although 
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forward references could be used to create cyclic dependencies, this is highly discouraged because 
it can lead to inconsistent scene graphs, and because the -echo command-line option cannot 
properly resolve such dependencies. Forward referencing is useful for systems that put together 
scene files from different sources. 


2.7.1 Options 


options "name" 
option_statements 
end options 


Options blocks contain rendering modes. An options element must be specified to render a 
scene. There is a variety of option_statements that can be listed in the options. Most of them can 
be overridden with an appropriate command-line option; see appendix A. The following option- 
statements are supported: 


2.7.1.1. Sampling Quality 


contrast r g b [a] 
The contrast controls oversampling. If neighboring samples differ by more 
than the color 7, g, 2, a, supersampling is done as specified by the sampling 
parameters (see below). Default for a is the average of r, g, and b. The recursive 
supersampling algorithm controlled by samples modifies the contrast based 
on the recursion level: at sample level 0, the contrast is used directly; at sample 
level 1, the contrast is doubled (effectively requiring a higher contrast to force 
another subdivision), and so on. Negative levels divide the contrast, 1.e. use a 
fraction 5, 4, and so on. In general, the contrast is multiplied by 2 at the 
supersampling level /evel, which is bounded by samples. The default is 0.1 
oh Mok gee 


This is the primary means of image quality control. Typically values are 0.1 
for r, g, b, and a. Values such as 0.2 or 0.3 reduce quality; lower values increase 
quality. Values less than 0.05 do not further increase quality in most cases. 
r,z,b,a can be specified separately to allow physiologically correct contrast 
values; the human eye is much more sensitive to different shades of green 
than blue and red, and can only poorly distinguish shades of blue. The a 
value should be set to 1.0 if the matte (alpha) channel is not needed; it is also 
possible to set a lower than r, g, b to generate matte channels with a higher 
quality than the color image. If the a value is missing, it is set to the average 
of r, g, b. Note that for high-quality rendering, the samples parameters must 
be adjusted. 


time contrast 7 g b [a] 
The time contrast controls the amount of temporal supersampling for 
motion blurred scenes. The number of temporal samples is approximately 
proportional to the inverse of the time contrast value. Default for a is the 
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average of r, g, and b. Using values for time contrast that are higher than 
contrast can speed up motion blur rendering at the price of more grainy 
images without degrading the quality of spatial antialiasing. The default is 
0.2 0.2 0.2 0.2; much higher than the spatial contrast. For fast motion blur, 
an alternative non-adaptive sampling technique can be used by setting the 
time contrast to 0 0 0 and minimum and maximum sampling to the equal 
relatively high value, such as 2 2. Also see the scanline rapid?” mode for 
an alternative high-speed motion blurring algorithm. 


samples [ minin; | maxint 


This statement determines the minimum and maximum sample rate. Each 
pixel is sampled at least 2*””” times and at most 2?””** times in each direction. 
If min is 0, each pixel is sampled at least once. Positive values increase the 
sample rate; negative numbers reduce the sample rate to less than one initial 
sample per pixel (infrasampling). mn defaults to —2, which means that at 
least one sample per 4 x 4 pixels is taken. If mn is chosen too small, small 
features may be lost if all samples happen to miss it (if it is found just once in 
any pixel of a task, mental ray will analyze the feature and render it correctly). 


If no min value is given, max — 2 is used by default. The defaults for min 
and max are —2 and 0, respectively. It is recommended to use max values 
larger than or equal to min + 2; the difference should not be higher than 3. 
Typical values for min and max are —20 for low-quality preview rendering, 
—11 for medium-quality rendering, and 02 or 13 for high-quality renders. 
Note that while this option offers simple control of rendering quality, it is 
recommended to control quality with the contrast option, which allows 
much finer control and deals more gracefully with high-contrast cases where 
the samples option can leave aliasing due to the hard cutoff. The samples 
statement should be used only as a hard sampling limit. 


If a filter options statement is used to set a filter other than box 1 1, min 
and max must be set to at least 1 1 for mental ray 2.0, or at least —1 0 for 
mental ray 2.1 or later. mental ray 3.0 enables jittering by default, unless max 
is less than 1. 


samples Minin, MaXin, defminin, defmaxin,?' 


mental ray 3.1.2 accepts two optional extra parameters that set the default 
object sample limits. In mental ray 3.1.2, objects may constrain sampling of 
the pixels they cover. The defminjn, and defmaxjn, parameters apply to pixels 
where no objects are seen, or all the objects that are seen have no samples 
limit. mental ray will never take fewer than 2””” and more than 2”* samples, 
and in areas with no object sample settings it will further reduce that range 
to 24” through 24", The defaults are —2 0 -128 127; the latter two are 
markers for “no further restrictions” because they are outside the —2 0 range. 


samples collect NUM int? 


Rapid Motion shading is controlled by the second argument of the -samples 
option, which is also used by all other rendering algorithms. Rapid Motion 
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also has a separate collection and compositing phase, which controls the 
number of samples per pixel to use for computing a pixel value. Due to 
motion blurring, this number can differ from the number of shading samples 
taken because shading samples are cached and re-used along the motion path. 
Increasing the collect rate improves motion blurring at little performance 
cost, unless the -samples parameter is so low that extra shading sampling 
points are forced. Unlike the -samples arguments, the num argument is a 
linear count. The default is 27°°7”"?", 


samples motion NUMint? > 


Determines at how many points in time a moving object is sampled in Rapid 
Motion mode. The default is 1, which means that a moving object is sampled 
once at shutter open time, and this result is blurred across the motion path. 
Higher values than 1 sample at more points during the shutter interval. 


filter box|triangle|gauss|mitchell|lanczos [width [height]] 


filter 


The filter statement specifies how multiple samples are to be combined into 
a single pixel value. The filter defaults to a box filter of width and height 1.0, 
which is the fastest of the filters. This option allows changing the filter kernel 
or the filter size. The available kernels are: box, triangle, Gauss, Mitchell, and 
Lanczos. The size of the filter is specified in pixel units. If no height is given it 
is taken to be equal to the width. Filters must be larger than 0.0. If the size of 
the filter is not specified, default values are used. These are 1.0 for box, 2.0 for 
triangle, 3.0 for Gauss and 4.0 for Mitchell and Lanczos. The default height 
is the same as the default width. Larger filter sizes result in softer images and 
may reduce rendering speed slightly, while values smaller than the defaults 
can introduce artifacts. Filters must be larger than 0.0 but sizes smaller than 


1.0 are generally wasteful since they will discard some samples. 
filter filter 


weight weight weight 
box triangle Gauss 
1 1 1 
YR / 
sample sample sample 
0 distance 0 distance 0 distance 
- size /2 0 size / 2 - size /2 0 size / 2 - size /2 0 size / 2 
filter filter 
weight weight 
Mitchell Lanczos 
1 1 
sample sample 
0 distance 0 distance 
- size /2 0 size / 2 - size /2 0 size / 2 


The box filter sums all samples in the filter area with an equal weight. The 
triangle filter functions has the shape of a pyramid centered on the pixel, 
which means that samples at the center of a rendered image pixel contribute 
more than more distant samples. The Gauss filter weights the samples using 
a Gauss curve that is cut off at an ellipse centered on the pixel. The Mitchell 
and Lanczos filters are both approximations of the theoretically ideal sinc 
filtering function, cut off after its second lobe. In most cases, the Mitchell 
filter gives better results. For these two, a filter width of 4.0 corresponds to 
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a frequency cutoff of 2.0 pixels, the Nyquist frequency. In order to use non- 
default filters, the limits for the samples statement must specify min = —1 
or greater, and max = 0 or greater (mental ray 2.0: 1 1 or greater). Otherwise 
a warning will be printed and the filter statement ignored. 


filter clip mitchell|lanczos [width [height]|*' 
These are variants of the regular Mitchell and Lanczos filters that clip the filter 
result to the range of samples under the filter. Mitchell and Lanczos filters 
have negative coefficients, which can cause ringing around sharp contrasts. 
Clipping prevents ringing. 


jitter jitter 

The jittering factor introduces systematic variations into sample locations. 
Without jittering, samples are taken at the corners of pixels or subpixels. 
Jittering displaces the samples by an amount calculated by lighting analysis. 
This is used to reduce artifacts. Jittering is turned off by default in mental ray 
2.x, and on by default in mental ray 3.0 if the maximum sampling is at least 1 
(at lower sampling densities jittering introduces artifacts). Jittering is turned 
off by specifying a jitter of 0.0. To turn jittering on, use a jitter value of 1.0. 
In mental ray 2.1, jittering works best in ray tracing mode; in mental ray 3.0 
it works equally well with ray tracing and scanline modes. 


2.7.1.2 Hardware Rendering’’ 


hardware offlonlall --° 


Specify which objects should be rendered with hardware rendering: off 
disables hardware rendering (this is the default), on uses hardware rendering 
for all materials that specify a hardware shader, and all uses hardware 
rendering for all objects and tries to find hardware substitutes for materials 
that do not specify an explicit hardware shader. The most useful mode is a11. 
Note that this option only selects which objects are eligible for hardware 
rendering, but mental ray may still fall back on software rendering for objects 
for which no appropriate hardware shaders are available. This is controlled 
separately by the following options. 

hardware cgl|nativelfast* -- [force ]}° 

This option controls how hardware shaders are selected for an object that is 

eligible for hardware rendering, as specified by the previous option. mental 

ray will try all approaches allowed by this option in turn: 


cg means that mental ray will first look for shaders implemented in NVIDIA’s Cg 1.2 shader 
programming language. This is the default. 


native looks for shaders implemented in the OpenGL 2.0 native shader programming language, 
which is less powerful than Cg. 
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fast uses hardcoded OpenGL materials that do not involve programmable shaders at all. This is 
limited to simple Gouraud models. 


force specifies that the search stops here, and objects that cannot use any of the above methods 
use a simple gray default material. If force is not specified, mental ray will fall back on software 
rendering for the object. 


The hardware options can be combined. For example, -hardware all cg native fast 
force -- will render all objects with the best available hardware shading method but never with 
software; this is useful for fast preview rendering. The option -hardware all cg native --~ is 
best for quality rendering, and so on. 


2.7.1.3 Tessellation Quality 


approximate technique [ mining MaXin, | all 
This statement overrides all approximations for base surfaces (i.e. the surface 
before applying displacement), and free-form surfaces without displacement, 
in geometric objects. See section 2.7.14 for a more detailed description of 
approximations. Here is a brief summary of technique, which is a list of one 
or more of the following: 


view 

tree 

grid 

fine 

[regular] parametric u_subdiv [v_subdiv] 
length edge 

distance dist 

angle angle 

spatial edge 

curvature dist angle 


Like in object approximation statements, the subdivision limits min and 
max can be specified how often a triangle can be subdivided. The defaults 
for min and max are 0 and 5, respectively; 5 is a very high value because 
every increment of 1 can quadruple the number off triangles in the extreme 
case. In objects, the approximation technique is followed by the surface or 
curve it applies to; in the options the keyword a11 indicates that an option 
approximation overrides all object approximations. The spatial and curvature 
statements are obsolete (they are only combinations of length, distance, and 
angle modes) and are retained for backwards compatibility only. 


approximate displace technique [| Minin, MaXjn; | all 
This statement overrides all approximations for displacement maps in 
geometric objects. Both kinds of approximation overrides are useful for 
temporarily reducing tessellation quality for previews to reduce tessellation 
and rendering time without redefining all objects, for example by specifying 
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approximate regular parametric 1.0 1.0 0 2 all 
approximate displace regular parametric 1.0 1.0 0 2 all 


mental ray 3.1 and higher offer fine approximation, which can efficiently 
approximate very detailed displacement maps and surfaces with a minimum 
of parameters: 


approximate fine view length 0.5 all 


max displace dist°”? 
This statement overrides all max displace statements in displacement-mapped 
objects with the maximum displacement distance dist. No displacement 
shader may return a larger value; that would cause truncated displacement. 
dist must be greater than 0.0. 


2.7.1.4 Motion Blur 


shutter [ delay ] shutter 

This statement controls motion blurring. The camera shutter opens at time 
delay‘ and closes at time shutter. The defaults are both 0.0. If shutter is 
equal to delay, motion blurring is disabled; if shutter is greater than delay, 
motion blurring is enabled. The normal range is (0, 1), which uses the full 
length of the motion vectors or motion vector paths*"'. It can be useful to set 
delay*' and shutter both to 0.5, which disables motion blurring but renders 
with an offset of one half frame, which allows bidirectional post-blurring 
in an output shader. Also see the scanline rapid’? mode for high-speed 
motion blurring. 


motion onloff>*? 
Normally the shutter statement controls whether motion blurring is 
enabled, and turns it on if there is a nonzero shutter interval. The motion 
statement overrides this and turns motion blurring on or off explicitly. For 
example, it is useful to define a zero shutter interval and then (order is 
important) turn motion blurring on, so that shaders get a correct state — 
motion vector. If motion blurring is turned off, this vector is not computed. 
motion steps num?! 
If motion blurring is enabled, mental ray can create motion paths from 
motion transforms, much like multiple motion vectors on vertices can create 
motion paths. This option specifies how many motion path segments should 
be created for all motion transforms in the scene. The number um must be 
in the range 1..15. The default is 1. If objects with motion transformations 
also specify motion vectors, the number of motion vectors per vertex must 
agree with the motion steps value. mental ray will add both sequences vector 
by vector, so both lists must have the same length. 
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2.7.1.5 Trace Depth 


trace depth reflectj,, [ refractin, [ sumint ]] 


The reflect parameter limits the number of recursive reflection rays. If it is 
set to 0, no reflection rays will be cast; if it is set to 1, one level is allowed 
but a reflection ray can not be reflected again, and so on. Similarly, refract 
controls the maximum depth of refraction and transparency rays (which 
implement transparency with and without index of refraction). Additionally, 
it is possible to limit the sum of reflection and refraction rays with sum. For 
example, if 3 3 4 is given, an eye ray may be reflected 3 times, or refracted 3 
times, or reflected twice and then refracted twice, or any other combination 
that sums up to at most 4. The defaults are 2 2 4. Note that custom shaders 
may override these values. 


2.7.1.6 Shadows 


shadow off 


shadow on 


shadow sort 


shadow segments 


This statement disables all shadows, and overrides instance and object shadow 


flags. 


Simple shadows are enabled. This is the most efficient and least flexible of the 
three shadow modes. If shadows overlap because multiple objects obscure 
the light source, the order in which these objects are considered (and their 
shadow shaders are called) is undefined. If one object is found to completely 
obscure the light, no other obscuring objects are considered. This statement 
turns off shadow sorting and shadow segments. Also see shadowmap motion 
below. 


This shadow mode enables shadow sorting. It is similar to the preceding 
shadow mode, but ensures that the shadow shaders of obscuring objects are 
called in the correct order, object closest to the illuminated point first. This 
mode is slightly slower but allows specialized shaders to record information 
about obscuring objects. If no such special shader is used, this mode offers 
no advantage over simple shadow on. 


Like with shadow sort, the shadow shaders are called in order. Additionally, 
shadow rays are traced much like regular rays, passing from one obscuring 
object to the next, from the light source to the illuminated point. Each such 
ray is called a shadow segment. This slows down rendering, but is required if 
volume effects should cast shadows (such as certain complex shaders like fur 
and smoke volume shaders). This mode requires support from the shadow 
shader, which must use the mzi_trace_shadow-_seg function to cast the next 
shadow ray segment. 
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shadowmap on|off|openg1|detail 


shadowmap only’? 


This flag turns shadow maps on or off for the entire render. Shadowmap 
parameters are specified for each light source. The default is off because 
standard shadowmaps, while often significantly faster, always assume opaque 
objects. The opengl mode causes mental ray to use OpenGL acceleration 
if available when rendering standard shadow maps. The same limitations 
apply as mentioned with the scanline option. Additionally, because of the 
difference of the rendering algorithm, OpenGL shadowmaps contain slightly 
different information from those generated with the regular algorithm, and 
the resulting shadows may look different. In particular, soft areas of shadows 
tend to be smaller and some areas may incorrectly be determined to be not 
in shadow. When OpenGL rendering of shadow maps is enabled, only the 
master host will participate, since the computation cost of the map is so small 
that the network transfer costs could not be recovered. 


mental ray 3.3 also supports detail shadowmaps that call shadow shaders 
attached to materials, and store the sequence of transparent shadow-casting 
objects per shadowmap pixel. For this reason they tend to be slower than 
standard shadowmaps. Detail shadowmaps behave like a combination of 
standard shadowmaps and raytraced shadows. Setting shadowmap detail 
in the options block will compute all enabled shadow maps as detail shadow 
maps. 


mental ray will render only shadow maps but not the color image. Only 
shadow maps with shadowmap file statements will be rendered and saved. 
This mode is turned off with shadowmap off. 


shadowmap rebuild onloff 


Determines whether all shadow maps should be recomputed. If this option 1s 
off (the default) shadow maps are loaded from files or reused from previously 
rendered frames if possible. If this option is on, no shadow map is reused — 
everything is recomputed. The default is off. 


shadowmap rebuild merge’? 


Specifies that shadowmaps should be loaded from files if available, but the 
regular shadowmap computation is performed anyway. The recomputed 
points are written top the existing shadowmap only if it is closer to the 
light. This is useful for building up shadowmaps for multipass rendering, so 
that objects from another render pass can still cast shadows on objects in the 
current pass. 


shadowmap motion on|loff 


Determines whether shadow maps should be motion blurred such that 
moving objects will cast shadows along the path of motion. Turning this 
option off can improve performance of rendering shadow maps slightly 
faster. The default is on. Note that since shadow maps do not deal with 
transparent objects and motion blurring introduces a form of transparency 
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at the edges, shadow map shadows can appear too large in the direction of 
motion if the object moves quickly. 


shadowmap bias bias? 
This option applies the specified shadowmap bias to all light sources, as if 
the bias had been specified in each of them. Specifying a bias has the effect 
of switching the shadowmaps from the normal halfway-point Woo trick to 
a fixed-distance algorithm. 


2.7.1.7. Rendering Algorithms 


trace onloff 

Normally, mental ray will use a combination of ascanline rendering algorithm 
and ray tracing to calculate samples of the scene. If trace off is specified, 
ray tracing is disabled, and mental ray will rely exclusively on the scanline 
algorithm. Since the scanline algorithm can only compute straight rays from 
the pinhole camera, reflection rays cannot be cast and refraction rays are 
computed like transparency rays, which do not allow control over the ray 
direction based on the index of refraction of the material. Lens shaders cannot 
alter the ray origin and direction. However, reflections onto environment 
maps do work. Shadows are also affected if ray tracing is turned off. Ray 
tracing is turned on by default. If off, this flag overrides instance and object 
trace flags. 


scanline on|off|rapid°*|opengl 

This statement allows turning off the scanline rendering algorithm. By 
default, mental ray tries to use a scanline algorithm for straight rays from 
the pinhole camera, such as primary rays. In most cases this gives better 
performance than pure ray tracing. Turning scanline off forces mental ray to 
rely entirely on ray tracing. This will generally slow down rendering but in 
some cases, for example when the task size is very small, the overhead of 
initializing the scanline algorithm may outweigh its benefit and turning it off 
can result in an improvement in speed. 


Rapid scanline’? mode uses a different scanline algorithm based on sample 
caching. It is usually slightly faster than regular sampling for static scenes, 
and substantially faster for motion-blurred scenes. Where regular motion 
blurring can reduce performance by a factor of up to 5, Rapid Motion 
blurring adds only about 25%-100% to the rendering time. Sample caching 
does introduce artifacts; in particular, moving mirrors and glass panes drag the 
reflection or refraction with them. The performance advantage is compelling, 
however. 


The opengl option will cause mental ray to use OpenGL hardware if 
present to further accelerate rendering. If possible, the master host will use 
OpenGL to generate acceleration data that the scanline algorithm then uses 
for intersection testing. Also see task size below. 
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Selects the binary space partitioning (BSP) ray tracing algorithm. This 
algorithm is often, but not always, faster. It is controlled by the bsp size 
and bsp depth statements. The BSP algorithm is the default. 


acceleration grid 


In mental ray 2.1, selects the static grid rendering algorithm. In mental ray 3.0, 
grid acceleration is not supported. In mental ray 3.1, selects the hierarchical 
voxel grid algorithm. Grids provide faster preprocessing especially on 
multiprocessor systems. Memory usage is more conservative and much easier 
to control than with the BSP algorithm. Speed is comparable to BSP but more 
scene-dependent, especially in mental ray 2.1. 


acceleration large bsp’” 


bsp size siz€jn 


bsp depth depthin; 


This is an alternative to regular bsp mode. All parameters are exactly the 
same, but a multi-level BSP tree is used. This slows down ray tracing by 
about 15-20%, but works much more effectively with geometry caching 
(and disk swapping) and allows far larger scenes to be rendered. Regular 
bsp mode can run into trouble when scenes begin to exceed a few tens of 
millions of triangles and poor scene coherence, like during final gathering. 
(Note that final gathering coherence can be improved with the finalgather 
falloff’ option). 


The maximum number of primitives in a leaf of the BSP tree. mental ray 
will subdivide BSP voxels containing more triangles, unless the maximum 
BSP depth (see next statement) is exhausted. This statement is used only if 
binary space partitioning is enabled. It has no effect on the other algorithms. 
Larger leaf sizes reduce memory consumption but increase rendering time. 


The default is 10. 


The maximum number of levels in the BSP tree. This statement is used only if 
binary space partitioning is enabled. Larger tree depths reduce rendering time 
but increase memory consumption, and also slightly increase preprocessing 
time. The default is 40. If there are too many triangles in the scene to fit 
into the BSP tree with the size specified by bsp size and bsp depth, the 
bsp size value is disregarded and larger leaves are created. This slows down 
rendering significantly. Larger bsp depth values of 50 or even higher often 
massively 1 improve rendering speed in BSP mode for larger scenes. The book 

“Rendering with mental ray” [Driemeyer 05] discusses how to choose good 
parameters in detail. 


bsp shadow on|off>*'! 


mental ray 3.1.2 and later support a separate shadow BSP tree that accelerates 
raytraced shadows. It can greatly improve speed if shadows are cast by 
simplified shadow-only objects because it is no longer necessary to populate 
the master BSP tree with large hero objects. This mode is off by default. 
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grid resolution xresjn [ yreSint Z7reSint | 


If the hierarchical grid algorithm?’ is used, this option sets the number of 
grid voxels in the X, Y, and Z dimensions. If only one number is given, it 
is used for all three dimensions. The default is 0 0 0, which selects a default 
computed at runtime. mental ray 3.1 can use subgrids to subdivide voxels 
with many triangles, so that scenes with local dense concentrations do not 
need to increase the global number of voxels just to capture the regions of 
high density. Incidentally, a grid resolution of 2 2 2 lets the grid algorithm 
degenerate to an octree algorithm. 


grid depth depthjn,>' 


grid size sizej' 


If the hierarchical grid algorithm?! is used, this option sets the number of 
recursion levels. If a voxel of a grid contains too much detail, it is subdivided 
by a subgrid for that voxel, which adds another level. The default is 2 for two 
levels (subdivided voxels cannot be subdivided again). 


If the hierarchical grid algorithm>' is used, this option sets the maximum 
number of triangles in a grid voxel. If there are more, and the grid depth 
permits it, the voxel is subdivided into a subgrid. Note that szzej,, must really 
be an integer; a floating-point value will cause the statement to be ignored, 
and a warning to be printed. 


2.7.1.8 Feature Disabling 


lens on|loff 


volume onloff 


geometry on|off 


displace on|off 


displace presample on|of 


Ignore all lens shaders if set to off. The default is on. 


Ignore all volume shaders if set to of f. The default is on. 


Ignore all geometry shaders if set to off. The default is on. 


Ignore all displacement shaders if set to of f. The default is on. 


£32 


Normally, mental ray presamples displacement-mapped geometry to find 
better bounding boxes of object fragments. This increases the startup time 
when rendering the displaced object, but rendering itself is much faster. The 
overall benefit can reach a performance factor of three. However, for quick 
previews it is sometimes desirable to get the first pixels as quickly as possible, 
regardless of the time it takes to complete the image; so this option allows 
disabling presampling. The default is on. 
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output onloff 
Ignore all output shaders if set to off. The default is on. File output 
statements are not affected. Note that all five disable options also affect 
shaders installed by phenomena. This means that the phenomenon can fail 
if it installs cooperating shaders that rely on each other’s existence, and one 
of them is disabled with these options. Phenomenon writers must allow for 
this case. The purpose of these options is fast preview rendering. 


autovolume on|off 
Autovolume mode>* enables a set of shader API functions that keep track of 
which volumes the current point is in: 71_volume_num_shaders, mi_volume- 
cur_shader, mi_volume_user-_color, and mi_volume_tags. 


photon autovolume onloff°” 
This mode enables autovolume computations for light sources that are 
photon emitters. If the light source is inside objects whose materials have 
photonvolume shaders, they are applied correctly to photons emitted by the 
light source. 


pass onloff*'! 
Multipass rendering’! performs operation on sample pass files. This option 
allows disabling all pass statements in the camera. See page 179 for more 
details about multipass rendering. 


lightmap on|off|only’* 
This mode enables rendering of lightmaps. By default, lightmaps are enabled. 
If this option is set to only, only the lightmaps but not the camera images 
are rendered. 


2.7.1.9 Caustics 


caustic on|off 

Caustics are turned on or off. They are off by default. Caustics are lighting 
effects caused by specular focusing of light rays, such as the irregular light 
patterns on the floor of a swimming pool. Note that caustics are only 
computed for light sources that specify an energy explicitly. The material 
shader that receives the caustics must also cooperate, and either the options 
block or the object to receive caustics must have appropriate caustic flag 
set. If off, this flag overrides instance and object caustics flags. 


caustic accuracy N [R| 
This option controls how caustics are estimated from the photon maps during 
rendering. The photon map is searched outwards from the intersection point 
and the photons that are encountered are examined. N specifies the maximum 
number of photons that should be examined, and R specifies the maximum 
radius that is searched for photons. If N is zero, the number of photons 
is only limited by R, and mental ray will pick an appropriate default. The 
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default for N is 100. If R is zero, a scene-size dependent radius is used instead. 


This is the default. 


caustic filter box|cone [filter_const] 
Filtering controls the sharpness of the caustics. Specifying a cone filter with 
the default filter_const of 1.1 generally has the effect that the caustics in 
the model looks sharper. Increasing the filter_const makes the caustics more 
blurry and decreasing makes it even sharper but also slightly more noisy. The 
filter_const must be larger than 1.0. 

caustic scale r g b [a}>* 

Caustics are multiplied by the specified color. Factors greater than 1 increase 

the brightness of the effect. 


photon trace depth reflectin, [ refractin, [ sumin: |] 

This option is similar to the trace depth option except that it applies to 
photons, not rays. The reflect parameter limits the number of recursive 
reflection photons. If it is set to 0, no photons will be reflected, if it is 
set to 1, one level is allowed but a photon cannot be reflected again, and 
so on. Similarly, refract controls the maximum depth of refracted photons. 
Additionally, it is possible to limit the sum of reflected and refracted photon 
levels with sum. Note that custom shaders may override these values. 


photonmap file "filename" 
Tells mental ray to use the file filename for the photon map. If the photon 
map file does not exist, it is created and the photon map is saved. If it exists, 
it is loaded and used without computing a new photon map. 


photonmap rebuild on|off 
If a filename is specified for the photon map (using the photonmap filename 
option), it is normally loaded and used if the file exists. If the photonmap 
rebuild option is turned on, any existing file will be ignored, and the photon 
map will be recomputed and an existing file will be overwritten. The default 


is off. 
photonmap only on|off>* 
If this option is set, only the photon maps but not the camera images are 


rendered. The default is off. 


2.7.1.10 Global Illumination 


globillum on|off 
Global illumination is turned on or off. The default is off. Global illumination 
permits effects such as indirect lighting, color bleeding, etc. Note that global 
illumination is computed only for light sources that have an energy specified 
explicitly; see section 2.7.5 for details. The material shader that receives global 
illumination must also cooperate. If off, this flag overrides instance and object 
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globillum flags. 


globillum accuracy N [R| 
This option controls how the photon map is used to estimate the intensity 
of global illumination. For a more detailed discussion of how this works, see 
the caustic accuracy option above. The default values are N = 500 and 
R = 0.0. For fast previews of global illumination, it can be useful to set N 
to 100. 


globillum scale r g b [a}** 
The irradiance part obtained from the globillum photonmap lookup is 
multiplied by the specified color. Factors greater than 1 increase the 
brightness of the effect. 


photonvol accuracy N 
This option controls how the photon map is used to estimate the intensity 
of caustics or global illumination within a participating medium. It applies 
to photon volume shaders, which compute light patterns in 3D space, such 
as volume caustics created by focused shafts of light cast by objects acting as 
lenses. The details are similar to what is described for the caustic accuracy 
option above. The default values are N = 30 and R = 0.0. 


photon trace depth, photonmap, photonmap rebuild onloff,andphotonmap only onloff 
have the same meaning as for caustics. 


finalgather on|off|only*’|fastlookup 

Final gathering for global illumination is turned on or off. The default is off. 
Final gathering means that when the illumination is computed at a diffuse 
point, the hemisphere above the point is sampled for indirect illumination. 
The illumination at those points is then computed as direct illumination plus a 
contribution from the photon map if global illumination is on. Final gathering 
is best suited for scenes with slow variation in indirect illumination, for 
example purely diffuse scenes. Final gathering eliminates the low-frequency 
variation in the global illumination that can often be seen if too few photons 
are used. Performance is kept acceptable by reusing and interpolating nearby 
final gathers. (Without final gathering, global illumination is computed by 
direct lookup in the photon map at the point — similar to the way caustics 
are computed.) 


The fastlookup’* mode also turns final gathering on, but also alters the 
global illumination photon tracing stage by computing the irradiance at 
every photon location, and storing it with the photon. This means that the 
photons carry a good estimate of the local irradiance, requiring far fewer 
final gathering points. Photon tracing takes longer than before and requires 
slightly more memory, but rendering becomes faster. 


mental ray 3.3 allow rendering only the finalgather map, and skipping 
rendering of the images with the only option. 
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finalgather accuracy [view] N [R; [Ro]] 

N controls how many rays should be used in each final gathering step 
to compute the indirect illumination. The default is 1000. Increasing this 
number makes the indirect illumination less noisy but also increases the 
rendering time. R; is the maximum radius in which a final gather result can 
be interpolated or extrapolated. The default maximum radius is computed 
based on the scene extent. R2 is the distance within a final gather result 
must be used for interpolation or extrapolation. The default is 10% of the 
maximum radius. Radius values are in world space units unless view?! is 
specified, in which case the values are in pixels. mental ray 3.4 works better 
and faster with smaller numbers of rays; 500 is a good value. It will be slower 
than 3.3 if the number of rays is left unchanged. 


finalgather falloff [ start] stop>? 

Limits the length of final gather rays to a distance of stop in world space. If no 
object is found within a distance of stop, the ray defaults to the environment 
color. Objects farther away than stop from the illuminated point will not 
cast light. Effectively this limits the reach of indirect light for final gathering 
(but not photons). The start parameter defines the beginning of a linear 
falloff range; objects at a distance between start and stop will fade towards 
the environment color. This option is useful for keeping final gather rays 
from pulling remote parts of the scene, which may not affect illumination 
very much, into the geometry cache. This allows mental ray to render witha 
much smaller memory footprint. See also mi_ray_falloff??. 


finalgather file "filename" 
Tells mental ray to use the file filename for loading and saving final gather 
points. If the finalgather file does not exist, it is created and the final gather 
points are saved. If it exists, it is loaded, and the points stored in it become 
available for irradiance lookups. If mental ray creates extra final gather points, 
they are appended to the file. This means that the file may grow without 
bounds. 
finalgather file [ "name", "name", ... ]°° 
mental ray 3.3 and later allow attaching a list of finalgather file names instead 
of a single file name. All files are read and merged. The first file is rewritten 
with the complete map like in the single-file case. 
finalgather filter size;.°? 
Final gathering uses an speckle elimination filter that prevents samples with 
extreme brightness from skewing the overall energy stored in a finalgather 
hemisphere. This is done by filtering neighboring samples such that extreme 
values are discarded in the filter size. By default, the filter size is 1. Setting 
this to 0 disables speckle elimination, which can add speckles but will 
better converge towards the correct total image brightness for extremely 
low accuracy settings. Size values greater than 1 eliminate more speckles and 
soften sample contrasts. Sizes greater than 4 or so are not normally useful. 
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finalgather rebuild on|off 
If a filename is specified using the finalgather filename option, it can be 
loaded and used if the file exists. If the finalgather rebuild option is 
turned on, any existing file will be ignored, and all final gather points will be 
recomputed and an existing file will be overwritten. The default is on. 
finalgather rebuild freeze’” 
This is equivalent to finalgather rebuild off, except that the final gather 
map, once created by reading it from a file or building it for the first 
frame, will never be modified (unless the finalgather file filename or 
the finalgather accuracy is changed). Extra finalgather points created 
during rendering will not be appended, and the finalgather file on disk will 
not be modified. The user is responsible to make sure that the finalgather map 
matches the scene and viewpoint in an animation. This is useful if multiple 
concurrent renderers share the map. 


finalgather trace depth reflectin, [ refractin, [ diffuse? * im [ sumint I]? 

This option is similar to -trace_depth but applies only to finalgather rays. 
The defaults are all 0, which prevents finalgather rays from spawning subrays. 
This means that indirect illumination computed by final gathering cannot 
pass through glass or mirrors, for example. A depth of 1 (where the sum must 
not be less than the other two) would allow a single refraction or reflection. 
In mental ray**only it is possible to trace diffuse bounces, previous version 
could trace specular or glossy bounces only. It is not normally necessary to 
choose any depth greater than 2. This is not compatible with mental ray 3.1 
and earlier, which used the trace depth (which defaults to 2 2 4) for final 
gathering. 


finalgather presample density BA 
This option controls the density of initial finalgather points. It increases 
(decreases if T < 1) the number of finalgather points computed in the initial 
stage approximately T times. 

finalgather scale r g b [a]** 

The irradiance part obtained from finalgather is multiplied by the specified 

color. Factors greater than 1 increase the brightness of the effect. 


2.7.1.11 Frame Buffer Control 


colorclip rgb|alpha|raw 
This option controls how colors are clipped into a valid range [0, 1] before 
being written to a non-floating point frame buffer or file. The rgb mode is 
the default. In this mode, RGB is first clipped to [0, 1] and alpha subsequently 
to |max(R, G, B), 1]. In alpha mode, alpha is first clipped to [0, 1] and RGB 
subsequently to [0, A]. In raw mode, RGB and A are both clipped to (0, 1] 
independently of each other. In all modes, the RGB components are clipped 
as specified by the desaturate option. The rgb and alpha modes ensure 
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that the resulting color is a valid premultiplied color. rgb should be used 
if the alpha channel is considered less important than preserving the RGB 
color and intensity. alpha mode is intended for alpha compositing, where 
the alpha channel is more important than the absolute color value to preserve 
correct transparencies. raw mode should only be used if no layering based on 
alpha is going to take place. This mode also forces the premultiply mode to 
on. It should be used with care because shaders might receive “illegal” colors 
(colors that cannot be composited in standard ways). 


desaturate onloff 


If a color is output to a frame buffer that does not have 32-bit (floating- 
point) precision, and its RGB components are outside the range [0, max], 
mental ray will clip the color to this legal range. If desaturation is turned off, 
the individual components are simply clipped into range. Otherwise, mental 
ray tries to maintain the brightness of the color by moving it towards the 
grayscale axis of the color cube, until the RGB components are in the legal 
range. max is determined by the colorclip mode. Desaturation is turned 


off by default. 


premultiply on|off 


dither on|off 


Premultiplication means that colors are stored with alpha multiplied to R, 
G, and B. For example, white at 10% opacity is not stored as (1, 1, 1, 0.1) 
but as (0.1, 0.1, 0.1, 0.1). This is the standard method in computer graphics 
to represent colors; mental ray always uses it internally and in all shaders. 
One implication is that R, G, and B can never exceed A if A is less than 
1.0. mental ray normally enforces this when storing color values into frame 
buffers. The premultiply off option instructs mental ray to always store 
colors unpremultiplied into frame buffers and files. It does this by undoing 
the internally applied premultiplication. (mental ray internally always works 
with premultiplied colors to present a uniform interface to shaders; since this 
is done with floating-point values there is no precision penalty.) This option 
is ignored if the colorclip raw mode is in effect. 


mental ray supports 8, 16, or 32 bits per color component. In some cases, 8 bits 
per pixel, as supported by all popular picture file formats, can cause visible 
banding when the floating-point color values calculated by the material 
shader are quantized to the 8-bit values used in the picture file. Dithering 
mitigates the problem by introducing noise into the pixel such that the round- 
off errors are evened out. Note that this can cause run-length encoded picture 
files to be larger than without dithering. Dithering is turned off by default. 


gamma gamma_factor 


Gamma correction can be applied to rendered and quantized (ie. not if the 
frame buffer is floating-point or RGBE) color pixels to compensate for 
output devices with a nonlinear color response. All quantized R, G, B, and 
alpha component values are raised to lovergamma_factor. The default gamma 
factor is 1.0, which turns gamma correction off. The reverse correction is 
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applied to all quantized texture images. 


frame buffer 7 ["type"] 


Define or delete user-defined frame buffer 7. Up to eight user frame buffers 
are supported, numbered 0 through 7. The frame buffer type type may be 
any standard image type allowed in an output statement, such as rgba or z. 
If the type is prefixed with a “+” sign, samples are interpolated; if prefixed 
with a “-” sign, it is padded. Padding is the default for all types. For example, 
+rgba_fp is an interpolated floating-point color frame buffer. After a frame 
buffer is defined, it may be used as the type fbn, with v in the range 0...7, 
in Output statements in cameras. The frame buffer is created in memory 
during rendering only if it is referenced by at least one output statement. 
The limitation to eight frame buffers has been removed in mental ray 3.4 and 


later. 


2.7.1.12 Scene Geometry 


camera Space 


object space 


All geometry is expected to be defined in camera space. Camera space 
assumes that the camera is at the coordinate origin (0,0,0) and looks 
down the negative Z axis. This means that geometry will typically have 
negative Z coordinates. This is the default. In camera space mode, instance 
transformations have no effect. This mode exists for backwards compatibility 
only and is not recommended. It is still the default, again for backwards 
compatibility reasons. This may change in the future. 


All geometry is expected to be defined in object space. Each object, light, 
and camera has its own coordinate space, typically but not necessarily 
with the coordinate origin (0,0,0) in the center of the object. The object 
coordinate space is positioned and oriented in world space with the instance 
transformation matrix (every object, light, and camera requires an instance). 
Object space allows multiple instancing where the object is placed in the 
scene more than once using multiple instance entities. 


2.7.1.13, Contours 


contour store shader 


If the camera contains a contour output statement, contour rendering is 
enabled and a contour store shader must be defined. This function stores 
information about the future contour edge, such as color, depth, normal, and 
other local information that is later used by the contour contrast shader to 
decide where the contour lines should be drawn, and by contour shaders to 
decide which colors and thicknesses the contours should have. Shader lists 
are not allowed here. 
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contour contrast shader 
If contour rendering is enabled, a contour contrast shader must also be 
defined. It decides where the contour lines should be drawn based on values 
stored by contour store shaders. The contrast shader compares two such 
value sets at a time. Shader lists are not allowed here. 


2.7.1.14 State Shaders’? 


state shader shader 

State shaders may be used to manipulate the state of mental ray before a 
shader is called. State shaders are invoked on four occations: When a shader 
state is created or destroyed, before a sample is taken, and after the sample 
has been taken. These four cases may be distinguished by constants passed to 
the shader from mental ray. (A shader state is a data structure that is passed 
to all shader, and provides general information about mental ray and the 
current intersection, and can be used top communicate between shaders.) 
State shaders are defined in the options block of the scene. 


2.7.1.15 Diagnostic Modes 


diagnostic grid off|object|world|camera § 
Draws a colored grid on all objects in the scene visualizing the coordinate 
space given. The distance between grid lines is § units. This is useful to 
estimate the size and distances between objects and to visualize the object 
space of objects. The off argument turns this mode off. 


diagnostic bsp off|depth|size 

This mode** visualizes the depth and leaf size of the BSP tree used for ray 
tracing acceleration. This works only if ray tracing is enabled (trace on) 
and the regular BSP algorithm is used (acceleration bsp). (It does not 
work for large bsp.) Both modes are the default. The image is scaled so 
that black means zero depth or size, and red or white means highest depth or 
size encountered (the absolute values are shown in the message output if the 
verbosity is 4 or higher). BSP diagnostics can be used to check how often the 
maximum BSP depth and the maximum leaf size were reached, as specified 
with bsp depth and bsp size statements. If this happens frequently, the 
parameters should be increased. 


diagnostic photon off|density|irradiance N 
When using photon maps, this mode replaces all material shaders in a scene 
with an internal shader that produces a false-color rendering of photon 
density, or the average of the red, green, and blue irradiance components. 
Photon density is the number of photons per unit surface area. N is the 
density (or irradiance) that is assigned to 100%, or red. The colors are, 
from 0% to 100%: blue, cyan, green, yellow, and red. Higher values fade 
to white. N can be given as zero in which case the appropriate maximum is 
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automatically found. This mode is useful when tuning the number of photons 
in a photon map and setting the various accuracy options, since the density 
(or irradiance) is estimated using those settings. The of f argument turns this 
mode off. 


diagnostic samples onloff 


This mode replaces the rendered image with a grayscale image showing the 
number of image samples made for each pixel. A black pixel has had no 
samples, whereas a white pixel has had the maximum amount as specified 
with the -samples option. In addition, a red grid is drawn indicating task 
boundaries. Samples that lie exactly on pixel boundaries are considered to 
belong to the lower and/or left pixel. This mode is useful when tuning the 
samples and the contrast options for optimal effect. 


diagnostic finalgather on|off*'! 


This mode shows final gathering points, as green dots for initial raster-space 
final gathering points, blue dots>* for final gathering points from per-object 
finalgather map files and red dots for render-time final gathering points. 


2.7.1.16 Miscellaneous 


face front|back| both 


task size sizé€j,, 


The front side of a geometric object in the scene is defined to be the side 
its normal vector points away from. By specifying that only front-facing 
triangles are to be rendered, speed can be improved because fewer triangles 
need to be tested for a ray. This works well unless there are objects whose 
back side is seen by refracted or reflected rays — with face front, the back 
side would not be visible. The default is face both, and works best if volume 
effects are used, which usually depend on closed volumes. 


This option specifies the size of the image tasks during rendering. Smaller task 
sizes are convenient for previewing, but also increase the overall rendering 
time. This option can also be used in order to optimize load balancing for 
parallel rendering. If the task_size is not specified, an appropriate default 
value is used. Note that very small task sizes can cause the scanline rendering 
algorithm to perform poorly and in such cases it may be desirable to turn it 
off. See scanline above. 


inheritance "function_name" 


To use parameter inheritance, a user-provided inheritance function must be 
specified. The function_name is the name of a C function linked to mental 
ray using a link command. No user-defined parameters are passed. The 
inheritance function is called for every pair of instances of which one is the 
parent (one level higher up in the scene DAG) of the other. The inheritance 
function must compute a set of inherited parameters from the parameters 
stored in these two instances. It is called even for the instances that contain 
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no parameters and for top-level instances; in this case the corresponding 
parameter argument pointer is zero. Inheritance shaders are not regular 
shaders; they are usually written by translator writers who need to emulate 
the inheritance methods used by the language to be translated. 
traversal "function_name">' 
The traversal statement is similar to the inheritance statement above, but 
installs function_name as a traversal function instead of an inheritance 
function. Traversal functions accessible through the options were introduced 
in mental ray 3.1.2; they have more control over the inheritance process. It 
is not possible to have both an inheritance and a traversal function. 


luminance weight ntsc 
This statement’* defines the RGB component weights used by the mi- 
luminance shader API function as (0.299, 0.587, 0.114), as defined by the 
NTSC standard. 


luminance weightr g b 
This statement’* defines the RGB component weights used by the mi- 
luminance shader API function as (r g D). 


2.7.2 Cameras 


camera "name" 
camera_statements 
end camera 


A camera describes a view of the scene, including the list of files to write, the lens shaders to 
use, volume shaders to be used as the global atmosphere or fog, global environment shaders 
that control what happens to rays that leave the scene, and other parameters. Cameras are scene 
entities that need to be placed in the scene with an instance element. In object space mode (see 
options element above), the location of the camera in world space is determined by the camera 
instance transformation. Note that the camera instance must be attached to the root instance 
group of the scene. See below for information on instance groups. 


2.7.2.1 Output Statements 


Cameras contain output statements that specify output shaders and output files to write to disk, 
and control which frame buffers mental ray creates and maintains during rendering. More than 
one output file can be created, and output shaders such as filters can be listed that operate on the 
final rendered image, before it is written to a picture file. outputs is one or more output statements. 
Output statements are very similar to shader lists, like lens shader statements, but the syntax 1s 
different to allow type specifications and output file names: 


output ["datatype"] "filetype" [options] "filename" 
output "datatype" "shader name" (parameters) 
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The first kind writes a picture to a file named filename, using the file format filetype. Normally, 
file formats imply a data type, but the defaults can be overridden by naming an explicit datatype. 
For example, the file type "rgb", which stands for aSGI RGBA image file, implies the data type 
" rgba" ; 


The options specify additional format related parameters. Currently, the "jpg" file format 
supports one option quality g, where gq is an integer value between 0 and 100. Lower values 
force higher lossy compression resulting in lower image quality. A quality value of 0 will cause 
the use of the default quality 75. For Softimage "pic" file formats, the options keywords even 
and odd are available to set the corresponding fields in the file header. 


The OpenEXR?> file format supports the compress option to select the compression mode. The 
available compression modes are none, rle, piz, zip, and pxr24. These mean no compression, 
run-length encoding, wavelet-based compression, Huffman dictionary compression, and an 
efficient but lossy (for floating-point data, which loses 8 of 32 bits) rounding method, respectively. 
The fastest ones are normally RLE or ZIP; PIZ usually achieves better compression but 1s 
much slower; if there are many very large textures a scene can render much slower. The 
OpenEXR manual recommends PXR24 for depth maps. mental ray 3.3 and earlier always use 
ZIP compression; mental ray 3.4 defaults to RLE. 


The second kind of output statement calls an output shader, such as a filter, that may operate on 
all available frame buffers. Here, the datatype may be acomma-separated list of types if the shader 
requires multiple frame buffers. Each type can be prefixed with a “+” or “-” to turn interpolation 
on or off. Interpolation is averaging for color, depth, and normal images and max’ing for label 
images. Interpolation is on by default for the standard color frame buffer and off by default for 
all others. For example, a shader that filters the standard RGBA image with a filter whose size 
depends on the distance of objects needs both the interpolated RGBA buffer and the interpolated 
depth buffer, and would have a data type "rgba, +z". mental ray creates all types of frame buffers 
requested by at least one output statement of either kind. 

The data type "rgbe"*'that stores high dynamic range RGBE data is normally used for formats 
that understand RGBE data ("hdr" or "cth"), but it can also be stored in any format that accepts 
8-bit RGBA. This will result in image files that cannot be displayed with standard viewers, but 
tools exist that can process such data. For example, the following output statement will store 
RGBE data in an RLA file: 


output "+rgbe" "rla" "filel.rla" 


Unless there is also a true floating-point buffer ("rgba_fp"), specification of the "rgbe" type 
will switch mental ray’s color frame buffer to RGBE mode because its high dynamic range is 
considered a superset of regular RGB. This can significantly reduce memory usage for large frame 
buffers, like 4000x4000, compared to floating-point frame buffers which are four times as large. 
Note that RGBE stores no alpha. In version 3.4 of mental ray, frame buffers are stored in frame 
buffer files on disk to allow arbitrary frame buffer sizes and arbitrary numvers of frame buffers. 
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The data types "£b0" through "fb7" refer to user frame buffers 0...7. The limitation to eight 
frame buffers has been removed in mental ray 3.4. User frame buffers are defined in the options 
statement using frame buffer statements. The actual data type of fb7 is the type of frame buffer 
n. For example, the output statements 


output "trgba" "rgb" "filel.rgb" 
output "fb0" "etip"” “Lile2.ct” 


write the standard frame buffer to the image file file1.rgb, and then write the contents of 
user frame buffer 0 to the image file file2.ct. This assumes that the options block contains a 
statement that defines user frame buffer 0, such as: 


frame buffer 0 "+rgba_fp" 


User frame buffers are empty unless some shader writes to them during rendering. Their purpose 
is to collect nonstandard image data during rendering, and to make the data available for output 
shading and image file writing. 


A special data type "contour" can be specified that enables contour rendering. Special contour 
output shaders must be specified that pick up the contour information from the contour cell 
frame buffer and compute a color image, which it can either put into the regular color frame 
buffer, or composite on top of the color frame buffer. In the latter case, one rendering phase 
creates a color image with contours. The color frame buffer can then be written to an image file 
using a regular image output statement. There is also a built-in contour output shader that creates 
a PostScript file instead of a color image; see section 3.22 on page 289 for details and examples. 


2.7.2.2. Multipass Rendering Statements?! 


Multipass rendering is a feature set that allows saving the results of rendering not in the form 
of image files, but in the form of sample lists. A sample is the result of a single primary eye ray, 
including all collected frame buffer information. Oversampling creates more than one sample per 
pixel, which are filtered to compute the pixel. Since multipass rendering operates on samples, it 
has access to the complete set of subpixel information, and does not suffer from pixel aliasing 
problems as image compositing does. mental ray also supports merging of multiple pass file, 
sample by sample, to generate the final filtered output images. Finally, mental ray supports pass 
preprocessing, which is a function with random access to a single pass file to perform operations 
such as subpixel motion blur postprocessing. 
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All multipass rendering functionality is controlled by a script in the camera definition, consisting 
of five types of statements: 


pass null 


pass [ Vieppestt ] 
write "filename" 


pass merge [ "types"? ] 

read [ "filename", "filename", ... ] 
[write "filename" | 
[ function ( parameters ) | 


pass prep [ "types"? ] 
read "filename" 


write "filename" 
function ( parameters ) 


pass delete "filename" 


Pass statement lists are similar to output statement lists, which also allow storing and processing 
data in order. 


pass null 
Deletes all pass statements defined in the camera. This is useful for 
incremental changes. It is executed at parsing time, when the scene is defined. 


pass 
Saves the current sample rectangle to the named file. The current rectangle is 
initially the rendered rectangle, but it is updated every time a merge shader 
has run. It is executed every time a rectangle has finished rendering. 


pass merge 

Merges two or more sample files into the current sample rectangle buffer, 
and optionally writes the result to another file. If other sample files should 
be merged with the current rendering result, it is not necessary to first write 
the rendered samples to a file and then to name that file in the pass merge 
statement; instead, an empty filename string ("") can be used to reference 
the rendered samples. If the merging function is omitted, mental ray uses a 
built-in default that supports depth and alpha blending of the main color 
frame buffer. The pass merge statement is executed every time a rectangle 
has finished rendering. 


pass prep 
Preprocesses a single pass file, and writes the result to another pass file. The 
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function has random access to all samples in the input and output file. It is 
called only once before rendering begins. 


The execution order of statements is important. Before rendering, all pass prep statements are 
executed in order; during rendering all pass and pass merge statements are executed in order for 
every finished rectangle; and after rendering all pass delete statements are executed. It is important 
to note that pass and pass merge statements are executed for every finished rectangle; this allows 
mental ray to minimize memory usage because only small sets of samples reside in memory at 
any one time. It also means that a pass prep statement cannot operate on the currently rendered 
pass because the pass prep function runs before rendering begins. In general, no two pass or pass 
merge statements should write to the same filename; this would result in sample data loss because 
of the per-rectangle interleaving. 


All files are created before reading begins; hence, a pass prep statement should not read froma file 
written to during rendering, and the write filename should not be identical to any read filenames 
in any statement. In general, all filenames written to should be unique. The pass delete statement 
was provided to clean up temporary pass files after rendering. Pass files can become quite large, 
often in the hundreds of megabytes if the resolution, oversampling parameters, and the number 
and size of frame buffers is large. Note that only mental ray 3.2 and later compress pass files. 


The types string controls which frame buffer are written to the pass file. Types apply to the write 
statement only. The syntax is the same as for output and frame buffer statements, such as +rgba_ 
fp,z". The default is the set of frame buffers defined by the output statement. Note that the main 
RGBA frame buffer si always written as floating-point RGBA, and that a depth (Z) frame buffer 
is always present, regardless of the type specification. 


See page 179 for more information on multipass rendering. 


2.7.2.3 Other Camera Statements 


There is a variety of camera_statements that can be listed in the camera. Some of them can be 
overridden by specifying an appropriate command-line option; see Appendix A. 


There are four camera statements that accept shader lists: output, lens, volume, and 
environment. As with all types of shaders, more than one shader can be listed, or more than one 
such statement can be given, to attach multiple shaders (or output files in the case of the output 
statement) to each type. In an incremental change (the incremental keyword is used before the 
camera keyword), each of the four first resets the list from the previous incremental change and 
does not add to the existing list, as multiple statements inside the same camera... end camera 


block would. 


The following camera_statements are supported: 


focal distance | infinity 
The focal distance is set to distance. The focal distance is the distance from the 
camera to the viewing plane. The viewing plane is the plane that the rendered 
scene is projected onto; its edges correspond to the edges of the rendered 
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aperture aperture 


aspect aspect 
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image. A common approach is to set the focal distance to the middle distance 
of the interesting objects in the scene and then set the aperture such that it 
is a bit larger than the horizontal extent of the objects in camera space. If 
infinity is used in place of the distance, an orthographic view is rendered. 
An orthographic view turns off perspective, all camera rays are parallel. 
View-dependent surface tessellation is not possible in orthogonal mode. 


The aperture is the width of the viewing plane. The height of the viewing 
plane is aperture divided by aspect. Together with the focal and aspect 
viewdefs, aperture defines the lens of the standard pinhole camera. 


This is the aspect ratio of the camera. The default is 1.33. In camera space, 
aperture is the width of the viewing plane and aperture divided by aspect 
is the height. The viewing plane is divided into pixels as specified by the 
resolution viewdef, so the aspect will result in nonsquare pixels if it is not 
equal to the X resolution divided by the Y resolution. For example, to render 
a PAL image at a resolution of 720 x 576 pixels, at an image ratio of 3:4 as 
defined by the PAL standard, pixels are slightly wider than tall, by a factor of 
2° . + = 1.0667. If the aspect ratio is corrected by this number, objects will 
appear undistorted on a PAL video display (but not on a computer display 
with square pixels). 


resolution Xin: Vint 


offset x y 


Specifies the width and height of the output image in pixels. 


Specifies an offset for the rendered image. The default is 0.0 for both values, 
which means that the image will be centered on the camera’s Z axis. Positive 
values translate the image up and to the right. The offset is measured in pixel 
units. 


window xlowin, ylowin, x-bighin y-highin 


clip hither yon 


Only the sub-rectangle of the image specified by the four bounds will be 
rendered. All pixels that fall outside the rectangle will be left black. 


The /ither (near) and yon (far) planes are planes parallel to the viewing plane 
that delimit the rendered scene. This is done to keep the scanline projection 
transformation stable; it does not affect raytracing. Points outside the space 
between the hither and yon planes will not be rendered (this does not apply to 
the infinite-radius environment maps because they are not geometric objects). 
The clip statement specifies the distance of the hither and yon planes from 
the camera. The defaults are 0.0001 for the hither distance and 1000000.0 for 
the yon plane. 
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volume [shader_list] 


This statement specifies volume (atmosphere) shaders. The atmosphere 
affects all rays passing through the space outside objects by attenuating 
the color of the ray. It is possible to specify a volume shader for the inside 
of objects too, by naming a volume shader in the material statement (see 
above). If no shader _list is specified, the existing volume shader list is deleted; 
this is useful in incremental changes. If a list is given, it replaces the current 
list if this is the first volume statement in the camera block, or it is appended 
to the current list otherwise. 


environment [shader_list] 


lens [shader_list] 


This statement specifies environment shaders. Environment shaders control 
the color returned by primary rays that, after leaving the camera, never strike 
any object in the scene. They are similar to environment shaders named in 
materials, which control reflection rays cast by the material shader that leave 
the scene without striking another object (or exceeding the trace depth). If 
no shader_list is specified, the existing environment shader list is deleted; this 
is useful for incremental changes. If a list is given, it replaces the current list if 
this is the first environment statement in the camera block, or it is appended 
to the current list otherwise. 


Lens shaders simulate lenses by changing the camera. If no lens shader is 
present, the camera is a pinhole camera that casts rays from the origin in all 
directions that strike the viewing plane, or an orthographic camera that casts 
parallel rays if focal infinity is specified. A lens shader accepts the origin 
and direction of the camera ray, modifies them, and casts a new primary 
ray. Examples for lens shaders includes fish-eye lenses that exaggerate the 
direction vector in a nonlinear way (there is a code example in the Shader 
section). Multiple lenses can be specified in the camera; the n-th lens shader 
receives the origin and direction computed by the 7 — 1st lens shader. If no 
shader_list is specified, the existing lens shader list is deleted; this is useful in 
incremental changes. If a list is given, it replaces the current list if this is the 
first Lens statement in the camera block, or it is appended to the current list 
otherwise. 


frame framein, [ time |] [field fteldin, | 


Every camera should contain the current frame number frame. The time in 
seconds can optionally be specified as tzme. Optionally, a field number field 
can be specified; by convention, field should be 0 when rendering frames, 1 
when rendering the first (odd) field, and 2 when rendering the second (even) 
field. If the field modifier is missing, the field number defaults to 0. mental 
ray currently does not use any of these values but makes them available to 
shaders. 


data "dataname"\null 


This statement attaches user data to the camera. The argument must be 
the name of a previously defined data element in the scene file. If nu11 is 
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specified instead of a data element name, a previously existing data reference 
is removed. 


2.7.3. Textures 


[ local ][ filter [ scale_const }] scalar texture "texture_name" "filename" 
scalar texture "texture name" [ widthin, heightin, [ depthint |] bytes ... 
writable scalar texture "texture name" [ widthin, heightin | depthin |] 
scalar texture "texture_name" shader_list 


[ local ][ filter [ scale_const ]] color texture "texture name" "filename" 
color texture "texture name" [ widthin, heightin, | depthin | 1 bytes ... 
writable color texture "texture name" [ widthin, heightin, [ depthin: | 1 
color texture "texture_name" shader_list 


[local] vector texture "texture name" "filename" 

vector texture "texture name" [ widthin, heightin, | bytes ... 
writable vector texture "texturename" [ widthin, heightint J 
vector texture "texture_name" shader_list 


Textures are lookup functions. They come in two flavors: lookups of two-dimensional texture or 
picture files or literal bytes, and procedural lookups. File textures require a file name parameter 
or a byte list; procedural textures require a shading function parameter. There are three types of 
texture functions: textures computing scalars, colors, and vectors. Which one is chosen depends 
on what the texture is used for. Textures are used as parameters to other shaders, typically material 
shaders. A material shader could, for example, use a color texture to wrap a picture around an 
object, or a scalar texture as a transparency or displacement map, or a vector texture as a bump 
map. The actual use of the texture result is entirely up to the shader that uses the texture. 


All of the above syntax variations define a texture texture_name. The texture_name should be 
quoted to avoid reserved words and to allow non-alphabetic characters. This is the name that the 
texture will later be referenced as. 


Verbatim or writable non-procedural textures can be defined by specifying the width and height 
of the texture and an optional depth (bytes per component, 1 or 2, default is 1; mental ray 3.0 also 
supports 4 for floating-point textures with four bytes per component). For verbatim textures, a 
list of width x height x depth hexadecimal two-digit bytes follows, most significant digit first 
if depth is 2 or 4, in RGBA order for colors and UV order for vectors. Note that the brackets 
around the sizes are literally part of the .mi file, while the skinny brackets around depth denote 
that the depth is optional and not part of the .mi file. These textures are called verbatim textures, 
and should be used with care because they can increase the scene file size enormously. Writable 
textures are primarily useful as the output of light mapping. 


Non-procedural textures can also be defined by naming a texture or picture file. For a list of 
allowed file formats, see page 18. In this case, the sizes (width, height, and depth) are read from 
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the file. If the local keyword is not present, the file is read once on the master host and then 
transmitted over the network to all slave hosts that participate in the rendering. With the local 
keyword, only the file name is transmitted to the slave hosts; this requires the file exists locally 
on all slave hosts but reduces network transfer times drastically if many texture files or very large 
texture files are used. Filename rewriting is available for interpreting the remote filename locally, 
for example to translate between Unix and Windows NT paths. Maximum speed improvements 
are achieved if local files are memory-mapped pyramids (see the -p option of the imf_copy tool), 
and reside on physical disks and not on NFS-mounted file systems (NFS stands for Network 
File System, distinguishable by the nfs type in the output of the Unix df command). 


If the writable°®* keyword is present, the texture is written to a file after it was written by a 
shader. This kind of texture is used by lightmap shaders to write back the light mapping result. 
Light mapping involves scanning the surface of an object, and collecting data for each point. This 
data is later written to a texture file. A typical example is “baking” indirect illumination into a 
texture that can then be simply texture-mapped at a later render pass, instead of computing the 
information at rendering time. If writable is specified, local should be specified as well because 
the file should be written to disk on the master host only. 


The filter keyword, if present, enables texture filtering based on texture pyramids, a technique 
comparable to mip-map textures. during rendering. Filtered textures are preprocessed before 
rendering begins and use approximately 30% more memory. Filtering should be used when the 
texture is large and seen at a distance, such that every sample covers many texture pixels. Without 
filtering, widely spaced samples “overlook” the areas between the samples; filtered textures 
perform a filter operation to take the skipped areas into account. The compression of the texture 
on the viewing plane can be scaled by the optional scale value if necessary. 


When loading a texture image, it is checked whether the texture is memory-mappable. This is the 
case if the texture file has the special uncompressed .map format. If this is the case, the texture is 
not loaded into memory but mapped into virtual memory. Memory-mapped textures use far less 
physical RAM and no swap space, but they use virtual memory. Memory mapping is especially 
useful for large textures that are not used often (i.e., many or most of its pixels are not sampled or 
the textured object is small or far away from the camera), but is recommended for all nontrivial 
texture images. Memory-mapped textures are implicitly also local textures. Memory-map textures 
should be created with the imf_copy utility, with the -p option to create pyramids. 


Procedural textures are defined by naming a shading function with parameters; the shading 
function can either be one of the built-in functions or an external function from a code or link 
command. 


When a shader evaluates a texture by calling a texture evaluation function, the program either 
looks up non-procedural shaders by looking up the texture in the range [0, 1) in each dimension, 
or it calls the named shader in the procedural case. The shader is free to interpret the point for 
which it evaluates the texture in any way it wants, two-dimensional or three-dimensional. 
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2.7.4 Materials 


material "material_name" 
[opaque] 
shader_list 
[displace [shader_list]] 


[shadow [shader_list]] 
[volume [shader_list]] 
[environment [shader_list]] 
[contour [shader_list]] 
[photon [shader_list]] 


[photonvol _ [shader_list]] 
[lightmap [shader_list]] 
end material 


Materials determine the look of geometric objects. They are referenced by material_name in the 
geometry definition in object statements (see below). Lights and textures cannot be referenced 
by objects; they are referenced by the material which uses them to compute the color of a point 
on the object’s surface. All built-in material shaders accept textures and light instances as shader 
parameters. 


When a primary ray cast from the camera hits an object, that object’s material shader (the first 
shader_list) is called. The material shader is mandatory in mental ray 3.2 and earlier; it may 
be omitted in mental ray 3.3 or higher in fully transparent objects. Such objects are useful as 
hull objects for volume effects such as visible light cones. Such objects will generally specity 
shadowmap off?” as well. 


The material shader then calculates a color (and certain other optional values such as labels, Z 
depths, and normal vectors that can be written to special output files). This color may then be 
modified by the optional volume shader if present. The resulting color is stored in the output 
frame buffer, which is written to the output picture file when rendering has finished. In order to 
calculate the color, the material shader may cast secondary reflection, refraction, or transparency 
rays, which in turn may hit objects and cause other (or the same; multiple objects may share 
a material) material shaders to be called. The material shader bases the decision whether to 
cast secondary rays on its parameters, which are part of the scene description and may contain 
parameters such as the material’s diffuse color or its reflectivity and transparency, light instances, 
and textures. The parameters depend entirely on the material shader. In this sense, material shaders 
are “primary” shaders that get help from “secondary” texture and light shaders. 


It is possible to specify a shader type such as shadow without following it with a shader_list. 
This is useful if an incremental change is done to the material. The incremental change leaves 
the contents of the material undisturbed except where explicitly rewritten, so the shadow shader 
list remains intact. It can be replaced by specifying a new one, but it can only be deleted with a 
shadow keyword not followed by any shaders. In an incremental change, the first statement (say, 
volume) first resets the old volume list; every subsequent volume statement in the same material 


block adds to the list. 


The material_name should be quoted to avoid conflicts with reserved names and non-alphabetic 
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characters. The opaque flag, if present, informs mental ray that this material is not transparent 
(i.e., it does not cast refraction or transparency rays and always sets its alpha result value to 
1); this allows certain optimizations that improve rendering speed. The material shader and its 
parameters are the only mandatory part of a material. 


There are several optional functions that can be listed in a material. The displacement shader is a 
function returning a scalar that displaces the object’s surface in the direction of its normal, or in 
arbitrary directions. Displacement shaders can be applied to both free-form surface objects and 
polygonal objects. 


The shadow shader is called when a shadow calculation is done, and the shadow ray from the light 
source towards the point in shadow intersects with this material. The shadow shader then changes 
the color of the ray, which is initially the (possibly attenuated) color of the light to another color, 
typically a darker or tinted color if the material is colored glass. It returns black if the material 
is totally opaque, which is also the default if no shadow shader is present. Shadow shaders are 
usually reduced versions of the material shaders; they evaluate transparencies and colors but 
cast no secondary rays. Shadow shaders are only required for transparent objects. If global 
illumination is enabled, no shadow shaders should be used because global illumination provides 
a more powerful way to compute light transmission, and using two “competing” methods at the 
same time for the same object may produce incorrect results. 


It is possible to use the material shader as a shadow shader; material shaders can find out whether 
they are called as material or shadow shaders and do only the required subset in the latter case. 
This is done by naming the material shader after the shadow keyword, and giving no parameters 
(i.e., giving ()). mental ray will notice the absence of parameters and pass the material parameters 
instead. If the shadow shader has no parameters of its own, it is not defined whether it receives a 
pointer to the material shader parameters, or a pointer to a copy of the material shader parameters. 


A volume shader affects rays traveling inside an object. Volume shaders are conceptually similar 
to fog or atmosphere shaders of other rendering programs. When a ray (either from the eye 
or from a light source) hits this material, the volume shader, if present, is called to change the 
color returned by the ray based on the distance the ray has traveled, and atmospheric or material 
parameters. A volume shader can also be named in the camera (see above); that shader is used for 
rays traveling outside objects. It is the material shader’s responsibility to determine inside and 
outside of objects. 


The environment shader is called when a reflection or refraction ray cast by the material shader 
leaves the scene entirely without striking another object. For example, the environment shader 
may map a texture on a sphere with an infinite radius surrounding the scene. (This is another 
example for an application of a texture; a texture name must be used as a parameter for the 
environment shader for this to work.) The camera statement also allows naming an environment 
shader; that shader is used when the ray leaves the scene without ever striking any object (or 
exceeding the trace depth). 


If a contour shader is given, it is called when contours are enabled with an appropriate output 
statement in the camera element, and certain contour store and contour contrast shaders are 
specified in the options element. For more information on contour rendering see section 2.8. 
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If caustics or global illumination computation is enabled, the photon shader is called during 
a preprocessing stage (before rendering) to determine the light distribution in the scene. Like 
shadow shaders, photon shaders without parameter lists are called with the material shader 
parameter lists. 


A volume photon shader affects photons traveling inside an object. When a photon hits this 
material, the volume photon shader, if present, is called to trace the photon through the volume. 
Volume photon shaders are to volume shaders what photon shaders are to material shaders. 


The lightmap shader is available only in mental ray 3.0. If present, it is called for the object that 
the material is attached to, and is expected to create a light map or other information collection 
about the object that can be saved to disk or used during rendering. In its most common form, 
the shader creates a texture that contains the illumination of the object; hence the term “light 


>” 


map . 


Materials can be replaced with phenomena. In all places where the name of a material may be 
given, the name of a shader that references a phenomenon declaration of type material is legal. 
Given the following scene fragment: 


declare phenomenon 
material "phen_mtl" (color "param") 
material "mtl" opaque 
"shader" ("diffuse" = interface "param") 
end material 
root material "mtl" 
end declare 


shader "mtl_sh" "phen_mtl" ("param" 1.0 0.7 0.3) 


the name mt1_sh can be used like a material_name, for example in polygon or free-form surface 
definitions in objects. For more information on material phenomena, see section 2.5. 


Note that there are three ways to use materials in a scene: 


e Every polygon and surface in an object specifies a material. They can be omitted but default 
to the previous polygon or surface in the object, but this is only a syntactical simplification. 
Effectively, every polygon and surface brings its own material, and no material inheritance 
takes place. 


e If the object is marked tagged, polygons and surfaces do not specify materials but integer 
labels. In this case the inherited material in the instance is used. That material can use mi_ 
query to obtain the label and modify its behavior based on the label. 


e Asa variation of the previous method, the instance may specify not a single material but a 
list of materials. In this case, mental ray will use the m-th material in the list if the label of 
the intersected primitive is 7 (or the first material if the label is greater than or equal to the 
number of materials in the list). 
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See section 2.7.15 for more details on material lists and material inheritance. 


2.7.5 Lights 


light "light name" 
shader _list 
[originxyz ] 
[ direction dx dy dz | 
end light 


Lights have a large number of optional parameters that are used if global illumination, caustics 
or shadow maps are enabled. These techniques use a preprocessing step that analyzes how light 
travels through the scene. Lights that participate in this preprocessing stage must specify a number 
of extra parameters. For clarity, regular lights and more specialized lights are shown separately: 


light "light_name" 
shader_list 
[ emitter 
[ area_light_primitive |] 
[ origin 
[ direction 
[ spread 
[ visible | 
[ tag 
[ data 


[ energy 
[ exponent 


[ caustic photons 
[ globillum photons 


[ shadowmap 
[ shadowmap 
[ shadowmap resolution 


shader_list | 


RZ | 
dx dy dz | 
spread | 


label; i 


[ "data_name" |nu11 ]] 


rgb] 

exp | 

store ine| emitint |] 
store ine| emitint |] 


[ on| off ]] 
[ detail ]]°° 
reSint | 


[ shadowmap detail samples numjn, |°° 


[ shadowmap samples 
[ shadowmap softness 
[shadowmap file 

[ shadowmap camera 

[ shadowmap bias 

[ shadowmap accuracy 


NUMint | 

size | 
"filename" | 
"cameraname" 

bias | 

epsilon | 


i 


[ shadowmap [colorlalpha] ]°° 


end light 


This statement defines a light source. All light sources need a light shader, such as the mib_light- 
point shader in the base shader library, or another shader linked with a code or link command 
(see above). "shader" above stands for the quoted name of the shader. Like any other shader, a 
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parameter list (possibly empty) enclosed in parentheses must be given. The parameters depend 
on the particular shader; they include the light color, attenuations, and spot light directions. The 
declaration of the shader determines which parameters are available in the parameters list; see 
section 2.1 for details on shader parameters. 


mental ray distinguishes three kinds of light shaders: point lights, giving off light in all directions; 
directional lights (also called infinite lights), whose light rays are all parallel in a particular 
direction, and spot lights which emit light from a point along a certain direction. Point lights 
must define an origin but no direction. Directional lights must define a direction; starting 
with mental ray 3.4, they can optionally have an origin that defines a plane whose normal is 
aligned with the light direction, and behind which no light is emitted. Spot lights must define an 
origin, a direction, and a spread. The spread defines the maximum angle of the cone defined 
along the direction in which the spot produces illumination. The value of spread is the cosine of 
this maximum angle; it must be between 1 (infinitely thin) and 0 (hemisphere). Spot lights often 
use a directional attenuation, but this is purely a function of the shader that is independent of the 
spread and direction keywords in the light definition. All types of lights can be turned into 
area light sources. 


After the definition, the light source can be instanced with an instance statement that references 
light name. The instance can then be referenced in parameter lists of shaders (such as a material 
shader) by listing the light instance name. Material shaders normally have an array parameter 
accepting one or more light instances, which they loop over to accumulate the contribution by 
each light (unless they rely solely on the global light list). Light instances are one of the standard 
data types that are available for shader parameters. The light name should be quoted to avoid 
clashes with predefined words, and to allow non-alphabetic characters. 


A label integer can be attached to a light using the tag statement. Labels are not used by mental 
ray in any way, but a shader can use the mi_query function to obtain the label of a light and 
perform light-specific operations. 


Also, user data can be attached with a data statement. The argument must be the name of a 


previously defined data element in the scene file. If the argument is missing, a previously existing 
data reference is removed. 


2.7.5.1 Area Light Sources 


Any point or spot light may be turned into an area light source by naming an area_light_primitive. 
Area light sources generate soft shadows because shadow-casting objects may partially obscure 
the light source. Six types of area light primitives are supported: 


rectangle [x9 Yo Zo X1 V1 Z1 sampling | 


disc [x y z radius sampling ] 
sphere [ radius sampling | 
cylinder [axis radius sampling | 
user sampling 


object object_inst sampling 


2.7. Scene Entities 119 


The common sampling substatement is optional: 


[ u_samples v_samples [level [low_u_samples low_v_samples ]}] 


All three area light types are centered at the origin position in the light definition. A rectangular 
area light is specified by two vectors that describe the lengths of the edges; a disc area light is 
specified by its normal vector and a radius; a sphere area light is specified only by its radius; and 
a cylinder area light is specified by its axis and radius. Note that the orientation of the rectangle, 
disc, or cylinder are independent of the direction and any directional attenuation the shader 
applies, although both will generally be similar. Also note that the end caps of the cylinder are 
not sampled. 


mental ray 3.1 and higher support a user-defined area light source. This requires a special light 
shader that controls the points on which it is sampled, instead of leaving the sample point location 
to mi_sample_light. The light shader will be called in a loop until the shader decides it has been 
sampled enough, or when the sample limit (u - v) is reached, and returns (miBoolean) 2. User 
area light sources also do not apply the optimization that cancels light rays under the horizon of 
the illuminated point. It is not necessary (or desirable, because of self-shadowing issues) to set 
state — pri to null. 


mental ray 3.1 also supports geometric area light sources for point lights, specified by the object 
keyword. Its first argument must be the instance of a single-group object that defines the geometry 
of the area light source. All points on the surface of the object will emit light uniformly. It is 
generally a good idea to keep the triangle count of the object as low as possible for maximum 
performance. The sampling rates usually have to be set much higher for object lights. 


The u_samples and v_samples parameters subdivide the area light source primitive. For discs and 
spheres, u_samples subdivides the radius and v_samples subdivides the angle. For a cylinder, u_ 
samples subdivides the height and v_samples subdivides the angle. When sampling the area light 
source, mental ray samples one point in each subdivision at a location precisely determined by 
the sample parameters and a predefined lighting distribution, and then combines the results. The 
default is 3 for each sample parameter, so an area light source without explicitly given samples 
parameters is sampled 9 times. 


If the optional /evel exists and is greater than 0, then mental ray will use /ow_u_samples and low_v_ 
samples instead of u_samples and v_samples, respectively, if the sum of the reflection and refraction 
trace level exceeds Jevel. The defaults for the low levels are 2. The effect is that reflections and 
refractions of soft shadows are sampled at lower precision, which can improve performance 
significantly. Since shaders have control over the trace level in the state, they can influence the 
switching depth, which can be used to sample soft volume shadows less precisely, for example. 
This optimization does not apply to user-defined area light sources because here the shader is in 
control of sampling rates, and if it is cut off early incorrect illumination can result. 


If the rectangle, disc, sphere, or cylinder keyword is specified without any of the following 
arguments, then the light source reverts to a non-area light source. This is useful for incremental 
changes. 
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2.7.5.2. Physical Correctness 


The second light form is for caustics and global illumination. (Caustics, global illumination, 
and final gathering implement the simulation of indirect illumination.) It requires specification 
of the light energy. The light energy is given as an RGB triple to allow colors, but the RGB 
values are typically much higher than the usual 0...1 range for colors. The number of photons 
stored from this light source in the preprocessing step is determined by store, and the number 
of emitted photons is determined by emit, if specified. When either limit is reached, photon 
emission stops. If store is 0, emit must be specified and storing is unlimited (this requires mental 
ray 2.1.37 or later). Physical correctness demands an 4 power law for energy falloff, causing the 
energy received from a light source to fall off with the square of the distance to the light source. 
However, the exponent parameter allows modification of the power law to -.. For any exp other 
than 2, physical correctness is lost, but for achieving certain looks it is often useful to use exp 
values between 1 and 2 to reduce the falloff, and better approximate classical local illumination 
non-physically correct lights. 


For caustics, one can specify a caustics photons value that controls the number of caustic photons 
stored during caustics preprocessing. Similarly, a globillum photons value can be specified for 
global illumination. Typical values range from 10,000 to 100,000; larger values improve accuracy 
and reduce blurriness. 


Light sources are by default invisible. However, area lights can be made visible by adding a 
visible flag to the light. Any visible flags on non-area lights are ignored since they have zero 
size. Light visibility cannot be inherited from the instance. It reduces performance if the number 
of visible lights is very large. Visible light sources ensure that the direct contribution of the light 
to the camera is not lost, and energy conservation is maintained in the rendered image. 


2.7.5.3 Shadowmaps 


Shadow maps are controlled per light source using the information about the light source type 
and the information provided by the shadow map keywords. Shadow maps are supported for 
spot lights with a cone-angle less than 90 degrees (i.e. spread > 0), for directional lights, and for 
point lights. A shadow map is activated for a light source by specifying the shadowmap keyword. 
The resolution of the shadow map which controls the quality and also the amount of memory 
used is specified with the shadowmap resolution keyword, which specifies the width and height 
of the shadowmap depth buffer in pixels. The shadowmap softness and shadowmap samples 
keywords determine the type of shadow produced with the shadow map; if the softness is zero a 
sharp shadow is generated. If softness is larger than zero, shadowmap samples different samples 
will be taken from the shadowmap, on a square region the size of shadowmap softness. This 
will make the boundaries of the shadows appear softer. 


The softness is specified in internal space units on the shadow map projection plane. For 
directional lights, an orthographic projection is used, so the softness will be constant in the 
scene, the soft region having roughly the given softness value in size. For other lights, because 
of the projective projection used, apparent softness will increase with distance from the light. 
This means that much smaller softness values are usually required for spot lights than directional 
lights. If an excessively high softness value is specified, a warning will be given during rendering. 
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Very high values tend to blur the shadow out of existence. The number of samples determines 
the quality of the soft shadow. 


The shadowmap bias statement*? specifies that mental ray should not use the distance to the 
halfway point between the two closest shadow-casting objects (this is called the Woo trick), but 
the distance to the closest plus the bias value. This is useful for shadowmap merging’. A bias 
value of zero re-enables the Woo algorithm. The bias value can also set in the options; this applies 


to all lights. 


If shadowmap merging’’is enabled, mental ray will load the shadowmap file from disk, if 
available, and also compute the shadowmap. It then uses the closest distance to determine whether 
a point is in shadow. This is useful in conjunction with multipass rendering, where the scene is 
divided into passes that are rendered separately. If the objects are sorted into passes front to 
back, with the frontmost rendered in the first pass, this allows front objects to cast shadowmap 
shadows on objects in later passes even though these objects are not present in the the later pass. 
The merged shadowmap is saved back to the shadowmap file. Note that shadowmap merging 
is not compatible with the halfway-point Woo trick, so it is necessary to specify a shadowmap 
bias either in each light source with shadowmaps to be merged, or globally in the options block. 
Merging does not work for detail shadowmaps. 


The shadowmap file statement can be used to specify a shadow map file in which the shadow 
map will be saved the first time it is rendered, and subsequently loaded every times it is used. In the 
case of point lights, six different files will be saved, each for a different direction (the resolution 
of each file will be lower so that the total number of pixels rendered will be approximately 
resolution x resolution). If objects in the scene move, the old shadow map files should be deleted 
to prevent loading and re-using outdated shadow maps. If the filename contains the # character, 
it will be expanded by mental ray into a hash code number identifying the transformation of the 
light instance. This is useful when a light is multiply instanced, because it allows distinguishing 
between files representing multiple instances of the same light. However, the user must take care 
to remove obsolete files or they will eventually fill all available disk space. 


Shadow maps are saved in the .zt file format, which is basically an 8-byte header followed by 
uncompressed floating-point pixel data. mental ray 3.2 and later use a format variant that works 
like .zt with some light space information appended. The extra information makes loading 
shadowmaps for lights that have moved, or scenes whose bounding box axes have changed, 
unambiguous. This avoids a problem of switching light axes when a shadowmap is transplanted 
from one scene to another. 


For spot light sources, the extent of the shadow map 1s determined by the spread parameter. For 
directional light sources, the extent of the shadow map is determined by the extent of the parts 
of the scene that cast shadows. For example, in a scene with small objects on a large background 
polygon, the small objects casting shadows should have a shadow flag, while the background 
polygon should not. Then the extent of the shadow map will only cover the small objects that 
cast shadows. If the large background polygon also has the shadow flag, the extent of the shadow 
map will be larger, and the shadow map will lack detail at the small objects where detailed shadows 
are needed. 


mental ray 3.3 allows attaching a camera to a spot or directional light source. This is not the 
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standard camera that defines the viewpoint from which the scene is rendered; it is simply a 
container for the following camera fields: 


e The resolution, if specified, overrides the shadowmap resolution in the light source 
definition. It can be nonsquare. 

e The window settings of the camera restricts shadowmap sampling to the specified portion 
of the shadowmap. The window is clipped to the shadowmap resolution specified in the 
light. 

e The offset settings shift the shadowmap relative to the shadowmap plane. 

e The aperture, focal, and aspect values define the field of view of the light source. The 


aperture is computed from the light spread value automatically for the spot case; it must be 
provided in the camera for the directional case. 


All other camera fields are ignored. A light camera does not have a camera instance; the light 
instance defines the necessary transform matrix. Treating a light like a camera is an useful 
abstraction for properly defining the light orientation. Note, however, that the spread value 
for spot lights must still be set and does not have a direct equivalent in the camera paradigm. 


2.7.5.4 Detail Shadowmaps>’”’ 


A different algorithm for calculating shadowmaps may be invoked by setting shadowmap detail. 
This algorithm is acombination of standard shadowmaps and ray traced shadows. Unlike standard 
shadowmaps, the detail shadowmap algorithm invokes shadow shaders at intersection points with 
shadow-casting geometry. 


The shadowmap detail samples parameter may be used to set the number of samples per pixel 
taken when computing a shadowmap pixel. A value of 7 means that n x n samples are taken 
per pixel, each involving a shadow intersection including a shadow shader call at some varying 
subpixel coordinate inside the shadowmap pixel. 


The shadowmap accuracy parameter determines how far two depth values of a sample have to be 
separated in order to be considered two distinct values. Selecting this value too small will result in 
larger memory and compute resource requirements for detail shadowmaps. Selecting it too large 
will lead to visible artifacts. mental ray tries to use a reasonable default value for the accuracy. 


shadowmap color is the default choice for detail shadowmaps. This setting indicates that all color 
channels of the shadow shader are used for the shadowmap calculation. If shadowmap alpha is 
set, then only the intensity values of the color transmission coeffiencents are used. 


In general, detail shadowmaps need less resolution than standard shadowmaps, since they may 
take more samples per pixel. Still, detail shadowmaps tend to be more expensive to compute than 
standard shadowmaps because of the shadow shader calls. They may even be more expensive 
than raytraced shadows. However, their cost may be offset by repeated reuse over several frames. 
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They may also be more efficient with time and memory resources than raytraced shadows for 
motion blurred shadows. 


The file format used to store detail shadowmaps is incompatible with the file format used to 
store regular shadowmaps. The entire file format is tile-based and only those tiles computed or 
used during a rendering will be stored in the file. New tiles may be dynamically added during 
rendering of new frames. Detail shadowmap files tend to be larger than regular shadowmap files 
since more information per pixel is stored. 


Detail shadowmaps cannot be used in segmented shadow mode, and they do not support 
shadowmap merging. 


2.7.6 User Data 


data "name" 
[tag labeljn; | 
bytecountin, L bytes list J 
end data 


data "name" 
[tag labelin; | 
" filename" 
end data 


data "name" 

[tag labelin; | 

declaration name (parameters) 
end data 


User data is arbitrary data stored in the scene file, which can be passed to shaders as a shader 
parameter of type data. This is useful for large amounts of data that is shared by several shaders, 
or too large or complex to be defined with individual shader parameters. There are three ways to 
define user data: 


e asaraw byte list. The list is a sequence of hexadecimal byte strings, each consisting of pairs 
of digits in the range 0..f, and enclosed in single quotes. Each string can be no longer than 
1024 bytes (2048 digits); if this is not sufficient more strings must follow. Note that the 
angle brackets must be in the scene file literally. The bytecount is the total byte count in the 
square brackets, regardless of how many quoted strings it is split up into. 


e asa file name. The file will be opened and its binary contents are read into memory. 


e as a structured parameter list. This is the only user data type that will be properly byte- 
swapped if used on a network of hosts with different byte orders. The parameter definition 
works exactly like the definition of shader parameters, and also need to be declared in the 
same way except that the declaration begins with “declare data” instead of “declare 
shader”. 
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Shaders see a tag if they evaluate a parameter of type data. This tag can be accessed with the mu_ 
query modes miQ_DATA_*, especially miQ_DATA_PARAM for accessing the data payload, and miQ_ 
DATA_NEEDSWAP for determining if a raw byte block (the first two data definition methods) need 
swapping by the shader. 


2.7.7 Light Profiles*! 


lightprofile "name" 


format ies 

file "filename" 
[ flags flagsine | 
[ hermite degreeint | 


[resolution xreSing yresint | 
end lightprofile 


Light profiles*:' such as IES or Eulumdat are files supplied by lamp vendors to describe their 
products. They contain a mesh of measured light intensities. The light profile block in the scene 
file allows loading a light profile file on disk, and converting the data into an internal format that 
is efficient for lookup in light shaders using the mi_lightprofile_sample (or mi_lightprofile_value) 


shader interface function. 


The only supported light profile format supported at this time is IES and Eulumdat. Other 
formats such as CIBSE may be supported in later versions of mental ray. The format statement 
may not be omitted. 


The file statement names the file supplied by the lamp vendor. 


The flags statement can be used to override the horizontal sample order in an IES file. There are 
two IES file types in common use, type B and type C. The IES standard defines that samples are 
stored in counter-clockwise order. Type C files conform to this standard, but about 30% of the 
type B files deviate from the standard and store samples in clockwise order, without giving any 
indication in the IES file that mental ray could use to switch the order. (Sometimes there is an 
informal comment.) If flags is 1, mental ray assumes clockwise order contrary to the IES standard 
for these incorrect type B files If flags is 2, mental ray assumes the normal counter-clockwise 


order. Type A IES files are not supported. Flags have no effect on Eulumdat light profiles. 


At this time only linear and cubic interpolation (hermite 1 or hermite 3) are supported. The 
resolution statement defines the precision of this interpolation by specifying the number of 
points on the smoothed mesh; for linear interpolation it always matches the resolution of the 
sample mesh in the profile file. 


2.7.8 Objects 


All geometry is specified in either camera space or object space, depending on the corresponding 
statement in the options statement (see section 2.7.1). In camera space mode, the camera is assumed 
to sit at the coordinate origin and point down the negative Z axis, and objects are defined using 
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camera space coordinates. In object space mode, the camera location is determined by its instance, 
and objects are defined in local object coordinates that are positioned in the scene with its object 
instance. Every object, camera, and light requires an instance. Camera space mode is only used 
for backwards compatibility with mental ray 1.x, and is now obsolete and not recommended. All 
existing integrations of mental ray on the market use object space exclusively. 


The appearance of the object, such as color and transparency, is determined by naming materials 
in the object definition. Before a material can be used in an object, it must be defined. Naming 
the material determines all aspects of the object’s appearance. No further parameters, textures, or 
lights need to be specified; they are all part of the material definition. 


The two most common approaches to materials and objects are to name all materials first and 
then all objects, which may simplify the implementation of material editors because all materials 
may be put in a separate file and then included in the .mi file using a $include command; or 
materials and objects may be interspersed. Either way, each material definition precedes its first 
use. 


All polygonal and free-form surface objects have the same common format in the .mi file: 


object "object name" 


[ visible [on|off] | 

[ shadow [on|off] | 

[ shadow [mode] }°* 

[ shadowmap [on|off] }>° 

[ trace [on| off] | 

[ reflection [mode] }°* 

[ refraction [mode] }°* 

[ transparency [mode] }°* 

[ select [on| off] }>* 

[ tagged [on| off] ] 

[ caustic [on| off] | 

[ globillum [onl off] | 

[ finalgather [on| off] | 

[ caustic [mode] | 

[ globillum [mode] ] 

[ finalgather [mode] }°* 
[finalgather file file (list) |’ 

[ face [frontlbacklboth] ]°* 

[ box [min, miny min, Max, Maxy Max;] is 
[motion box [min, Miny min, Max, MaxXy Max;] tc 
[max displace value |°* 

[ samples min max }*! 

[ data null|"data_name" |°* 
[ tag label_ number in, | 

[ file "file name" |°* 

[ basis list ] 

group 


vector list 
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vertex list 

geometry list 

approximation list 
end group 


end object 


The individual parameters are: 


e The object name object_name serves to uniquely identify the object. The name is not used 


by mental ray in any form except to give meaningful progress reports and error messages. 
Object names should be enclosed in double quotes to disambiguate them from reserved 
words. 


The visible flag causes the object to be visible. Most objects will have this flag set. Not 
setting it will make the object invisible to primary rays (those originating from the camera), 
which means it will disappear from the image. The optional boolean argument defaults to 
on. If no trace statement is present, it defaults to off (this is also true for all other boolean 


flags). 


In mental ray 3.2, transparency rays will also hit objects marked visible. In this case, 
transparency is not considered a special case of refraction, but as a scanline rendering 
feature. This apparent inconsistency permits using transparency effects even if ray tracing 
is turned off altogether. More importantly, it also keeps objects that have the visible flag 
but not the trace flag out of the BSP tree that is used to accelerate ray tracing, which has a 
significant performance impact. This tradeoff can become very significant for large scenes. 


The shadow flag causes the object to cast shadows. The standard case is specifying both the 
visible and shadow flags. If an object is very complex, it may be desirable to set only the 
visible flag but not the shadow flag, and create a second object that resembles the first 
one but is much simpler and set the shadow but not the visible flag on it. The effect is that 
the object appears unchanged, but shadow calculations see a much simpler shadow object 
that casts approximately the same shadow as the primary visible object would. Shadows are 
globally disabled if the options block specifies shadow off. In mental ray 3.4 the shadow 
mode specifies whether the object casts shadows (mode 1), receives shadows (mode 2) or 


both (mode 3). The default is mode 2. 


The shadowmap’” flag controls whether an object can cast a shadowmap. The default is on. 
For an object to cast shadowmap shadows, the shadow flag must be on as well. This flag 
is useful for transparent volume bounding objects called s, such as visible light cones, that 
are fully transparent but should not cast shadows. 


The trace flag serves a similar purpose as the shadow flag. Normally, it is always set along 
with the visible and shadow flags. It controls whether the object is visible to secondary 
(reflected or refracted) rays. If the reflecting or refracting objects are fuzzy or only slightly 
reflective or refractive, it may result in a considerable speedup to make the reflection and 
refraction rays see a much simpler object than primary rays would. Like with the shadow 
flag, this is achieved by not setting the trace flag in the primary, high-definition object, 
and create a second one that roughly resembles the primary object that has the trace flag 
(and perhaps the shadow flag) but not the visible flag set. Ray tracing is globally disabled 
if the options block specifies trace off. 
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The reflection>* flag controls whether the object is visible to reflection rays: 1 enables 
reflection casting, 2 enables reflection receiving, 3 enables both, and 0 neither. Default is 
mode 2. Note that “casting” is used in the sense of becoming visible in a reflective surface”, 
not as in “casting a ray”. This is similar to “casting a shadow”. 


The refraction°* flag controls whether the object is visible to refraction rays: 1 enables 
refraction casting, 2 enables refraction receiving, 3 enables both, and 0 neither. Default is 
mode 2. Again, “casting” means “casting a refraction”, which is the opposite from “casting 
a refraction ray”. 


The transparency’ flag controls whether the object is visible to transparency rays: 
1 enables transparency casting, 2 enables transparency receiving, 3 enables both, and 
0 neither. Default is mode 3. Once again, “casting” means “casting a transparency image”, 
which is the opposite from “casting a transparency ray”. 


The select?* flag makes the object subject to select-tracing. This feature is used by some 
applications to perform interactive object picking by sending a ray into the scene (perhaps 
where a user clicked the mouse) and receiving a list of objects visited by the ray. Only 
objects with the select flag will appear in this list. 


The tagged flag changes the way geometry is stored. Normally, every polygon, surface, 
and triangle comes with its own optional material. If an object specifies no materials, the 
material is inherited from the instance. Objects marked tagged do not store materials at 
all and always rely on the inherited instance material, and permit specifying a non-optional 
label integer in place of the material in polygon and surface definitions. (Non-optional 
means that a tagged object must contain one label integer for every polygon and surface.) 
This label can be accessed by shaders during rendering (not in displacement or output 
shaders) using the miQ_GEO_LABEL mode of the mi_query function. The idea is that a shared 
material distinguishes parts of the object by label integer, instead of attaching a different 
material to each polygon or surface. 


The caustic flag lets the object participate in optimized generation of caustics. A caustic 
is an illumination effect caused by light that undergoes specular reflections or refractions 
before it hits a diffuse object. For example a water surface casts irregular light patterns 
on the floor of a swimming pool. To simulate this effect, the material shader of the floor 
object must be written to pick up caustic light, and the light source must contain a caustic 
photon statement and contain appropriate photon energy settings. For optimized caustic 
generation, the options should specify caustic 0 and the water surface and floor objects 
must have the caustic flag set. Caustics are globally disabled if the options block specifies 
caustic off. 


The mode argument controls the caustic operation: 1 enables caustic casting, 2 enables 
caustic receiving, 3 enables both, and 0 neither. of f means that the object is invisible to 
caustic photons, and ’on’ is the same as 3. In the pool example, the water surface should have 
mode 1 and the floor should have mode 2. If the caustic keyword is given without mode 
argument, the mode defaults to on (that is, 3). If no caustic keyword is given, caustics 
detault to mode 0. 


The globillum flag lets the object participate in optimized generation of global 
illumination. Global illumination is an illumination effect caused by diffuse interreflection, 
such as a red table bleeding red color onto an adjacent white wall. To simulate this effect, 
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the material shader of both the table and the wall must specify photon shaders, the wall 
object material shader must be written to pick up global illumination light, and the light 
source must contain appropriate photon energy settings. For optimized global illumination 
simulation, the options should specify globillum 0 and the red table and white wall must 
have the globillum flag set. Global illumination is globally disabled if the options block 
specifies globillum off. 


The mode argument controls the global illumination mode: 1 enables global illumination 
casting, 2 enables global illumination receiving, 3 enables both, and 0 neither. The default 
is specified by the options. off means that the object is invisible to global illumination 
photons, and on (the default) enables global illumination interactions with this object. In 
the table example, the red table should have (at least) mode 1 and the white wall should have 
(at least) mode 2. If the globillum keyword is given without mode argument, the mode 
defaults to 3). 


If an object is very complex, it may be desirable to set only the visible flag but not the 
globillum flag, and create a second object that resembles the first one but is much simpler 
and set the globillum but not the visible flag on it. The effect is that the object appears 
unchanged, but simulation of global illumination is faster since a simpler object is used. 


The finalgather’* mode argument controls the final gathering mode: 1 enables final 
gather illumination casting, 2 enables final gather illumination receiving, 3 enables both, 
and 0 neither. Default is mode 0. off means that the object is invisible to final gather rays, 
and on (the default) enables final gathering illumination interactions with this object. 


The finalgather file°* file (list) argument allows to specify a file name or a list of file 
names with finalgather map(s) to be used for the object. If identical file names or file name 
lists are used for several objects, only one copy of finalgather map will be kept in memory. 


The face°’* statement controls face culling. The possible values are ’f’ (front), ’b’ (back), 
and ’a? (all). If not specified, the culling flag given in the options or in the state is used. 


The box’ statement specifies a bounding box for the object, in the space of the object. 
For polygons, this is easy to compute: the box components are simply the smallest (mn) 
and largest (max) point-in-space (v) vector components. For free-form surfaces, the box 
can in principle be derived in the same way; however, such a box would often be much too 
large, especially for NURBS. Boxes that are too large are legal but inefficient. If the box 
statement is omitted, mental ray will compute one from all vertices, which is also not very 
efficient. Boxes are required if the object is demand-loaded. The box should not include 
enlargement caused by displacement or motion. 


The motion box’* is similar to the box, but contains the minimum and maximum 
components of all motion vectors. Note that this is not the same as the smallest and 
largest vector; the motion box vectors are pieced together from the individual smallest and 
largest motion vector components. A motion box must be specified if the object has both a 
box and motion vectors. 


The max displace°’* statement specifies the maximum allowed displacement applied to 
object control points in local object space in normal direction. If a displacement shader 
returns a value grater than value, the rendered geometry may appear clipped and a warning 
is printed. If maxdisplace is omitted but the object is displaced, mental ray 3.0 prints a 
warning and tessellates the object immediately, which results in correct images but is not 
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very efficient. Displaced objects should always specify a maximum displacement. mental 
ray 3.1 and higher do not pretessellate and may truncate the displacement to 0.0, which 
causes it to disappear. 


A value that is too large generates correct images but puts more pressure on the cache, 
so rendering may use more memory and run more slowly. In particular, mental ray 3.1 
and higher may suffer serious performance losses, easily by an order of magnitude, if the 
displaced object uses fine approximations. If the maxdisplace value is too small, mental 
ray 3.0 may clip parts of the object; mental ray 3.1 and higher always limit the absolute 
displacement to the maxdisplace value. 


e The samples statement controls per-object oversampling. For all pixels that touch this 
object, the normal samples range specified in the options block is constrained to the min 
max range, such that at least 2””” and at most 2”** samples are taken. Constraints that 
exceed the min and max limits in the options block are ignored, so that the options can 
be used to force quick preview rendering without having to change all object sampling 
specifiers. If the pixel touches multiple objects, perhaps due to reflection or refraction, the 
highest min and the highest max are used. If the pixel touches no objects at all, the default 
limits defmin and defmax defined in the options block are used. The defaults are -128 127, 
which disables per-object sampling limits. 


e The tag specifies an arbitrary 32-bit number that identifies the object. mental ray normally 
uses the term /abel, but the keyword tag is retained for backwards compatibility. The term 
tag is used by mental ray to identify entries in the scene database; this is of concern only to 
shader writers. By specifying an appropriate output statement in the camera (see above), it 
is possible to cause mental ray to write a label file that, for each pixel, contains the label code 
of the object that the camera ray hits first. Exactly which label is stored is under the control 
of the material shader; using the label of the foremost object regardless of reflections and 
refractions is merely the default behavior. 


e The data°* statement attaches user data to the object. The argument must be the name 
of a previously defined data element in the scene file. If nul1 is specified instead of a data 
element name, a previously existing data reference is removed. 


e The file°* statement can be used to load the object from a file when mental ray enters 
its bounding box. A box statement, and also a motion box statement if the object has 
motion vectors and amax displace statement if the object is displaced, must be given too. 
The actual geometry in the group ... end group block must be omitted. The specified 
file must contain an exact copy of the object, except that the file statement is replaced 
with the group ... end group block and the incremental keyword must be specified 
before object. The object may have only a single object group (multigroup objects are for 
backwards compatibility with mental ray 1.x only, and not recommended for mental ray 2.x 
and 3.x). Demand-loaded objects are useful to avoid parsing and permanently storing large 
objects that may or may not be required for rendering. The -echo explode command-line 
option can be used to automatically create demand-loaded object files. 


e The basis list is a list of bases to be used in free-form surface descriptions. Only curves and 
surfaces use bases. For a list of supported bases, see section 2.7.10.1. The defined bases can 
be used in all groups that follow, until the end of the object. 


e Finally, an object groups contains the actual geometric representation. Multiple object 
eroups are supported for backwards compatibility with mental ray 1.9, but not 
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recommended; mental ray 2.x and 3.x will automatically convert a multigroup object to an 
instance group containing multiple sub-objects. 


At the end of each object group, approximation statements can be given that control 
the tessellation method. In polygonal object groups, the approximation is used only for 
polygons whose material contains a displacement shader. Free-form surfaces are always 
controlled by their approximations; see page 162 for details. 


The visible, shadow, trace, reflection, refraction, transparency, caustic, globillun, 
finalgather and face flags can be overridden by the instance using the standard inheritance 
mechanism. Instances can specify that a flag in the instanced object is turned on or off, or that 
it is left unchanged. The object flags are used only if all the instances from the root of the scene 
DAG down to the object all leave the flag unchanged. 


Object groups contain the actual geometry. All geometry needs vector lists and vertex lists. The 
vector list contains 3D vectors that can describe points in space, normals, texture vertices, basis 
vectors, motion vectors, and others. Vectors are anonymous, they are triples of floating-point 
numbers separated by whitespace without inherent meaning. They are numbered beginning with 
0. Numbering restarts at 0 whenever a new object group starts. 


mental ray also accepts a compressed binary format for vectors. Instead of three floating-point 
numbers, a sequence of 12 bytes enclosed in backquotes is accepted. These 12 bytes are the 
memory image of three floats in IEEE 854 format, using big-endian byte order. This format is 
intended for increasing translation and parsing speed when ray is connected to a native translator; 
it should not be used in files modified with text filters. Many filters and editors refuse to accept 
files containing binary data, or corrupt them. 


Vertices build on vectors. In the .mi format, there is no syntactical difference between polygon 
vertices and control points vertices for free-form surfaces; both are collectively referred to as 
eG ol Ler Tansee ; pee 

vertices” in this discussion. All vertices define a point in space and optional vertex normals, 
motion vectors, derivatives, zero or more textures and basis vectors, and user vectors: 


V indexin 

[n indexint | 

[d indexint indexint [ indexin;| indexing, indexin: | | |] 
[t indexin, [ indexing indexin: | |] 

[m indexint | 

[u indexin: 


Polygon vertices may use all of these. Free-form surface control points may use v and m only; 
the others are either computed analytically or are specified in other ways as part of the surface 
definition. 


Vv specifies the point in space, 
n specifies the vertex normal vector (ignored when the vertex is used as a curve or surface 


control point). A normal vector defines the orientation (vertical) of the surface at this 
vertex. 
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m specifies the motion vector. mental ray 3.1 permits up to 15 m statements per v statement 
for nonlinear motion paths. If multiple motion vectors are specified, the shutter time 
interval 0..1 is equally subdivided, and each motion vector specifies the motion from the 
origin specified by the v vector to the corresponding point on the path. In other words, 
multiple motion vectors do not form a connected chain but a bundle of “rays” originating 
at the same point v. 


t specifies a texture vertex with an optional X/Y basis vector pair for bump map calculation. 
There can be up to 64 t lines for any given v vertex. (The texture and basis vectors are 
ignored when the vertex is used as a curve or surface control point. Texture and basis 
information for surfaces is defined using a “texture surface”, described below.) 


d specifies a first and/or second surface derivative. First derivatives describe the UV 
parametric gradient of a surface; second derivatives describe the curvature. mental ray 
can compute surface derivatives analytically for free-form surfaces but not for polygons 
because polygons have no inherent UV coordinate space. Therefore, the d keyword must 
be used to define explicit surface derivatives for polygons. If d is followed by two indices 
they are taken to reference the first derivative dPdu and dPdv (with P being the point in 
space); if three indices follow they are taken to reference the second derivative d?Pdu?, 
d? Pdv?, and d?Pdudv; and if five indices follow the first two describe the first derivatives 
and the next three the second derivatives. Derivatives are not used by mental ray, they are 
made available to shaders only. 


u specifies a user vector. No constraints are imposed on user vectors. mental ray does not 
operate on them in any way, they are passed through with the vertex and can be picked 
up by the shader. 


Every vertex begins with a v statement and ends with the next v statement or with the start of 
the geometry description. All occurrences of index above reference the vector list; 0 is the first 
vector in this group. References of different types (for example, v and n) may not reference the 
same vector. As stated before, all vectors are 3D. If the third coordinate is not used (as is the case 
for 2D texture vertices, for 2D curve control points, and for 2D surface special points) it should 
be set to 0.0 by convention. If both the second and third coordinates are unused (as is the case 
for 1D curve special points), they should both be set to 0.0. 


Vertices themselves are numbered independently of vectors. The first vertex in every group is 
numbered 0. The geometry description is referencing vertices by vertex index, just like vertices 
are referencing vectors by vector index. This results in a three-stage definition of geometry: 


1. List of vectors 
2. List of vertices 


3. List of geometry 


The reason for this three-stage process is that it allows both sharing vectors and sharing vertices. 
This is best illustrated with an example. Consider two triangles ABC and ABD sharing an edge 
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AB. (This example will use the simplest form of polygon syntax that will be described later in 
this section.) The simplest definition of this two-triangle object is: 


object "twotri" 


visible 

group 
Oe 0,0 -0.0 
Lo. - 0.0. -O.0 
00>, 1.0, 0.0 
Lh) Co 100 
1a0- 248 O20 
0.0. 4,0 -0,0 
v O 
vi 
WZ 
ae 
v4 
v 5 


p "material_name" 0 1 2 
p345 
end group 
end object 


The first three vectors are used to build the first three vertices, which are used in the first triangle. 


The remaining three vectors build the next three vertices, which are used for the second triangle. 
Two vectors are listed twice and can be shared: 


object "twotri" 


visible 

group 
0.9 -O.02 -0,0 
1.0 0 “0.0 
U.0° 42.0" 0.9 
120° °T.0° 8.0 


sss a9 9 
NOWreENF O 


p "materialname" 0 1 2 
p345 
end group 
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end object 


The order of vector references is noncontiguous to ensure that the second triangle is in counter- 
clockwise order. Two vertices are redundant and can also be removed by sharing: 


object "twotri" 
visible 

group 

SP 


OvrD OOS 
ey EF CO O 
Oui0O°Or S 
oO O-'O 
oS ©. Ono 


<q sa64 4 
WNOrF © 


p "material_name" 0 1 2 
bis 2 
end group 
end object 


The need for sharing both vectors and vertices can be shown by specifying vertex normals: 


object "twotri" 


visible 

group 
0.0 O.0 0.0 
i.2 0.0 0,0 
0.0 1.0 0.0 
1. 1.0 -0.9 
0.0 90.0 1.0 
vo n4 
Vil’ 2 
wy 2 eS 
v3 n4 


p "material_name" 0 1 2 
pL as 
end group 
end object 


In this last example, both vector sharing and vertex sharing takes place. The normal in this example 
is actually redundant: if no normal is specified, mental ray uses the polygon normal. Defaulting to 
the polygon normal is slightly more efficient than interpolating vertex normals, if vertex normals 
are explicitly specified. 
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Two types of geometry can be contained in the geometry list, polygonal geometry and free-from 
surfaces. In the next sections the syntax of the definitions of polygonal geometry and free-form 
surfaces is described and illustrated by examples. 


If the optional mental matter product is available, objects can also contain subdivision surface 
geometry. Although part of the standard mental ray grammar (see the appendix), subdivision 
surfaces are not described in here. Refer to the mental matter manual instead. 


An object group permits only one type of geometry, either polygons or surfaces but not both. 
It is recommended that objects contain only a single object group, so normally objects are either 
polygonal or surface objects but not both at the same time. Also, vector sharing is supported 
only for vectors of similar types (point in space, normal, motion, texture, basis vector, derivative, 
or user vector. A vector may not be referenced by vertices once as a point in space and once as a 
normal, for example. 


2.7.9 Polygonal Geometry 


Polygonal geometry consists of polygons. For efficiency reasons, mental ray distinguishes simple 
convex polygons from general concave polygons or polygons with holes. Both are distinguished 
by keyword: 


c ["material name") vertex_ref_list 
cp ["material name"] vertex_ref_list 
p ["materialname"] vertex_ref_list 
p ["materialname"| vertex_ref_list hole vertex_ref_list ... 


If the enclosing object has the tagged flag set, mandatory label integers must be given instead of 
the optional materials: 


c label numberin, vertex-ref_list 
cp label numberin, vertex_ref_list 
p labelnumberin, vertex_ref_list 
p label_numberin, vertex_reflist hole vertex_ref_list ... 


The c keyword selects convex polygons without holes. The results are unpredictable if the 
polygon is not convex. The cp keyword is a synonym for c for backwards compatibility; c 
should be used in new translators. The p keyword also renders concave polygons correctly, and 
allows specification of holes, using one or more hole keywords, each followed by a vertex_ref- 
list. If all polygons within the same object group are simple convex polygons containing three 
sides (triangles), mental ray will pre-process them in a more efficient manner than non-triangular 


polygons. 


A vertex_ref_list is a list of non-negative integers index that reference vertices in the vertex list of 
the group described in the previous section. The first vertex in the vertex list is numbered 0. 


Any vertex index can be used in both polygon and hole vertex_ref_lists. A polygon with n vertices 
is defined by 7 index values in the vertex list following the material name. The order of the 
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polygon vertices is important. A counter-clockwise ordering of the vertices yields a front-facing 
polygon. The vertex list of a hole may be ordered either way. Any displaced polygon violating this 
rule, for example because it has been displaced such that its new normal points the wrong way, 
causes the error message “orientation of triangles inconsistent” and the surface to be dropped. 


The material name must have been defined before the object definition that contains the polygon 
definition, in a statement like 


material "material_name" 
end material 


In both cases, it is recommended to quote the material name to avoid conflicts with reserved 
words, and to allow arbitrary characters in the name. For a detailed description of material 
definitions, see section 2.7.4. Once a material name has been specified for a polygon, it becomes 
the default material. All following polygons may omit the material name. Polygons without 
explicit material use the same material as the last polygon that does have an explicit material. Not 
specifying materials improves parsing speed because no names must be looked up in the symbol 


table. 


If no material is specified, polygons remain without material; in this case the material from the 
closest instance up the scene DAG is used instead. This is called material inheritance. Tagged 
objects always inherit their material from the instance. It can distinguish polygons by using the 
miQ_-GEO_LABEL mode of the mi_query function during rendering (not in displacement shaders). 


The tessellation of polygons assumes that polygons are “reasonably” planar. This means that 
every polygon will be tessellated, but the exact subdivision into triangles does not attempt to 
minimize curvature. If the curvature is low, different tessellations cannot be distinguished, but 
consider the extreme case where the four corners of a regular tetrahedron are given as polygon 
vertices: the resulting polygon will consist of two triangles, but it cannot be predicted which of 
the four possible triangles will be chosen. 


The behavior will be different for convex polygons without holes (c keyword) and polygons 
which contain holes or are concave (p keyword). Convex polygons without holes are triangulated 
by picking a vertex on the outer loop and connecting it with every other vertex except its direct 
neighbors. If polygons are not flagged with the c keyword but do not have any holes an automatic 
convexity test is performed and if they are indeed convex they are triangulated as described. 
Convex polygons with holes and concave polygons are triangulated with a different algorithm. 
In any case a projection plane is chosen such that the extents of the projection of the bounding 
box of the (outer) loop have maximal size. If the projection of the polygon onto that plane 1s not 
one-to-one the results of the triangulation will be erroneous. 


If a textured polygon’s material contains a displacement map the vertices are shifted along the 
normals accordingly. If an approximation statement is given triangles are subdivided until the 
specified criteria are fulfilled; see section 2.7.14 for details. 
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2.7.10 Free-Form Surface Geometry 


Free-form surfaces are polynomial patches of any degree up to twenty-one. * Supported basis types 
include Bézier, Taylor, B-spline, cardinal, and basis-matrix form. Any type can be rational or non- 
rational. Patches can be explicitly or automatically connected to one another, or may be defined to 
contain explicitly defined points or curves in their approximation. Various approximation types 
including (regular) parametric, spatial, curvature-dependent, view-dependent, and combinations 
of these. mental ray 3.1 also introduces fine approximation, which can generate microtriangle 
tessellations very efficiently. Surfaces may be bounded by a trimming curve, and may contain 


holes. 


Surface geometry, like polygonal geometry, is defined by a series of sections. An object containing 
only surface geometry follows this broad outline: 


object "object name" 


[ visible [on| off] ] 
[ shadow [on| off] ] 
[ shadowmap [onl off] >? 
[ trace [on] off] | 


[reflection [mode] ]}°* 
[refraction [mode] ]** 


[ transparency [mode] ]°* 

[ select [on| off] }>* 

[ tagged [on|off] | 

[ caustic [on| off] | 

[ globillum [on| off] ] 

[ face [frontlback\both] }°* 

[ caustic [mode] ] 

[globillum [mode] |] 

[ box [min, min, min, max, maxy max,] }* 


motion box [min, min, min, max, max, max,] }* 
y y 
[max displace value ]°* 


[ samples min max }*'! 

[ data null|"data_name" |°* 
[ tag label number jn; | 

[ basis list ] 

group 


vector list 

vertex list 

[ list of curves | 

surface 

[ list of surface derivative requests | 
[ list of texture or vector surfaces | 
.. # more surfaces 

[ list of approximation statements | 
[ list of connection statements | 


*The algorithms used impose no inherent limit. The limit may be increased in future versions. 
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end group 
end object 


Curves, surfaces, approximations, and connections may be interspersed as long as names are 
defined before they are used. For example, a curve must come before the surface it is trimming, 
and an approximation must come after the surface to be approximated. Texture and vector texture 
surfaces must always directly follow the surface they apply to. The individual sections are: 


e The basis list must be specified at the beginning of the object definition, just before the 
group begins. Bases defined in this section are referenced by name in the curve and surface 
definitions to specify their degrees and types (Bézier, B-spline, etc.). 


The vector list in the group is a list of (x,y,z) vectors used to build control points later. 
This section is the same as the vector section used to build vertices for polygonal geometry. 


The vertex list that follows the vector list builds control points out of the vectors. This 
also works like the vertex list for polygonal geometry, except that no normals and texture 
vertices can be defined here (no n, t, d, or u statements may appear). Normals are defined 
implicitly by the surface, and textures are defined by texture surfaces instead as described 
below. Surface derivatives are generated if derivative keywords are present. Rational 
curves and surfaces specify additional weights at each vertex reference (see below). 


Curves may be defined and used as trimming curves, hole curves, and special curves. This 
section is optional; if no trimming curve is defined surfaces are untrimmed and end at the 
boundaries specified by the ranges of the bases used. Trimming a surface means to cut away 
portions that fall outside an outer boundary curve; holes cut away portions inside the hole 
curve. Special curves are curves that are always included in the tessellation; they can be used 
to define features like sharp creases that need to be tessellated consistently. Surfaces may 
also be connected along trimming curves. 


e The surface geometry list consists of surface statements, much like polygonal geometry 
that consists of p and c statements. A surface is defined by a surface statement, optionally 
followed by surface derivative request statements and one or more texture surface or 
vector surface statements. 


e Approximation statements give additional information about how a surface and its 
trimming, hole, and special curves are to be approximated with triangles. Various 
modes such as parametric, regular parametric, curvature-dependent, and view-dependent 
approximations can be selected, along with the precision. If there are approximation 
statements in the options statement (see Options, Tessellation Quality above), they 
override any approximation statements in the objects. 


For a description of vector lists and vertex lists, refer to page 130. 
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2.7.10.1 Bases 


When surfaces and curves are present within an object group, it is mandatory that at least one basis 
has been defined within the object. Bases define the degree and type of polynomials (denoted by 
Nij.n below) to be used in the description of curves or surfaces. Curves and surfaces reference bases 
by name. Every surface needs two bases, one for the U and one for the V parameter direction. 
Both can have a different degree, but must have the same type (for example, rational Bézier in U 
and Cardinal in V is not allowed). There are five basis types: 


basis "basis name" [rational] taylor degreejn; 

basis "basis name" [rational] bezier degreejn; 

basis "basis name" [rational] cardinal 

basis "basis name" [rational] bspline degreejn, 

basis "basis name" [rational] matrix degreej, stepsizein, basismatrix 


A parametric representation may be either non-rational or rational as indicated by the rational 
flag. Rational curves and surfaces specify additional weights at each control point. This flag is 
optional; it can also be specified in the curves and surfaces that reference the basis. 


The degree specifies the degree of the polynomials used in the description of curves or surfaces. 
Recall that the degree of a polynomial is the highest power of the parameter occurring in its 
definition. When bases of degree 1 are used control points are connected with straight lines. 
Cardinal bases always have degree 3. The degree and the type combined determine the length of 
the parameter vector and the number of control points needed for the surface. The meaning of 
the parameter vector differs for the different basis types. This is described in detail below. 


The supported polynomial types for curves and surfaces are bezier, bspline, taylor, cardinal 
and matrix. 


When a curve or surface is being evaluated and a transition from one segment or patch to the next 
occurs, the set of control points (the ‘evaluation window’) used is incremented by the stepsize. 
The appropriate stepsize depends on the representation type expressed through the basis matrix 
and on the degree. 


Consider a curve with k control points {v;,..., vp}. If the curve is of degree 7, then n + 1 control 
points are needed for each polynomial segment. If the stepszze is given as s, then the (1 +7)th 
polynomial segment will use the control points {vjs41,...,Visin+1}- For example, for Bézier 
curves s = ”, whereas for Cardinal curves s = 1. For surfaces, the above description applies 
independently to each parametric dimension. 


The basis_matrix specifies the basis functions used to evaluate a parametric representation. For 
a basis of degree 7 the matrix must be of size (7 + 1) x (21 + 1). The matrix is laid out in the 
order boo, boi, --. » Bon, --- 5 Bnn. Note that the generalization to the rational case for all 
representations is admitted in all cases. 


As an example, an object containing a nonrational Bézier surface of degree 3 in one parameter 
direction and degree 1 in the other parameter direction needs two bases defined at the beginning 
of the object like this: 
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object "mysurface" 
visible 
basis "bezi" bezier 1 
basis "bez3" bezier 3 


group 
The surface definition will reference the two bases by their names, bez1 and bez3. 


2.7.10.2 Surfaces 


A surface specifies a name and a list of control points. For both parametric dimensions it specifies 
a basis, a global parameter range, and a parameter list. Optionally, it specifies surface derivative 
requests, texture surfaces, trimming curves, hole curves, special curves and special points. Special 
curves and points are included as edges and vertices in the approximation (triangulation) of the 
surface. 


surface "surface name" "material name" 
"u_basis name" range u_param_list 
"v_basis name" range v_param_list 
hom_vertex_ref_list 
[ derivative_request | 
[ texture_surface_list | 
[ surface_specials_list | 


If the enclosing object has the tagged flag set, a label integer must be given instead of a material 
name (see page 127). This changes the first line of the preceding syntax block to: 


surface "surface name" label_numberin, 


The bases used in the definition of the surface must have been defined in the basis list of the object. 
They are referenced by their basis names. Their ranges consist of two floating-point numbers 
specifying the minimum and maximum parameter values used in the respective direction. 


The parameter_ists in the basis specifications define the number of patches of the surface and 
the number of control points. For bases of the types taylor, bezier, cardinal and matrix 
such a parameter_list consists of a strictly increasing list of at least two floating-point numbers. 
For bspline bases the parameter_lists specity the knot vector. If the B-spline basis to be used 
is of degree n, the knot vector (xo,...,% 7) must have at least g + 1 = 2(n + 1) elements. Knot 
values represent a monotone sequence of floating-point numbers but are not necessarily strictly 
increasing, i.e. x; < x;41. Moreover, they must satisfy the following conditions: 


(1) Xo < Xn+1 

(2) Xg—n-1 <Xq 

(3) x;<Xi4n for O<i<q-—n-1 
(4) We Tn He Liens Xq—n 
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where |tmin, tmax| 1s the range over which the B-spline is to be evaluated. Equation (1) demands 
that no more than 7 + 1 parameters at the beginning of the parameter list may have the same 
value. Equation (2) is the same restriction for the end of the parameter list. Equation (3) says that 
in the middle of the parameter list, at most 7 consecutive parameters may have the same value. 
To generate closed B-spline curves, it is often necessary to write a parameter list where the first 1 
and last m parameters in the list produce initial and final curve segments that should not become 
part of the curve; in this case equation (4) allows choosing a start and end parameter in the range 
bounded by the first and last parameter of the parameter list. 


The number of control points per direction can be derived from the number of parameters p, the 
degree of the basis 1, and the step size s. Their total number can be calculated by multiplying the 
numbers taken from the following table for each of the U and V directions. 


¥ of conol point 
Taylor (p —1)-(n+1) 
Bézier (p—1)-n+1 


cardinal Pra 
basis matrix (p—2)-stn+1 
B-spline pP=-—7=1 


Note that only certain numbers of control points are possible; for example, if the U basis is a 
degree-3 Bézier, the number of control points in the U direction can be 4, 7, 10, 13, and so on, but 
not 3 or 5. For B-spline bases of degree 3 the minimum number of parameters is 8 corresponding 
to 4 control points. 


Each vertex reference in the hom_vertex-_ref_list is an integer index into the vertex list of the 
current group in the object (index 0 is the first vertex). When the surface is rational, homogeneous 
coordinates must be given with the control points, by appending a floating-point weight to every 
vertex reference integer in the hom_vertex_ref_list. There are two methods for specifying weights: 
either a simple floating-point number that must contain a decimal point to distinguish it from an 
integer index, or the keyword w followed by a weight value that need not contain a decimal point. 
The w keyword method is recommended because it eliminates the requirement that numbers 
contain decimal points, so translators can use 4g format specifiers. Weights are used only if the 
surface is rational and ignored otherwise. If a weight in a rational surface is missing, it defaults to 
Aas 


The surface specials list is used to define trimming curves, hole curves, special curves, and special 
points (vertex references). A surface may be further modified by approximation and connection 
statements, as described below. 


For example, an object with a simple degree-3 Bézier surface can be written as: 


object "mysurface" 
visible 
basis "bez3" bezier 3 


group 
0.314772 -3.204608 -7.744229 # vector 0 
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0.314772 -2.146943 -6.932366 
0.314772 ~1.089277, -6:120503 
0.314772 “9.031611 ~-5.308641 
-0.660089 -2.650739 -8.465791 vector 4 
-0.660089 -1.593073 -7.653928 
-0.660089 -0.535407 -6.842065 
-0.660089 0.522259 -6.030203 
-1.634951 -2.096869 -9.187352 # vector 8 
-1.634951 -1.039203 -8.375489 
-1.634951 0.018462 =f .S6302T 
~1.634951. 1.076128 -6.751764 
-2.609813 -1.543000 -9.908914 # vector 12 
-2.609813 -0.485334 -9.097052 
-2,.6009813 0.572332 -8.285189 
-2.609813 1.629998 -7 .473326 
v 0 wd v2 Va # vertices 
v 4 v5 v 6 v 7 
v 8 v 9 v 10 ee 
v i2 vy is v 14 ¥ 18 
surface "surfi" "material" 
"bez3" 0.0 1.0 0.0 1.0 
“pezo” 0.0 1.0 oO 1.0 
0123 4°65°6 fs 3.20 31" 22 45 14 15 
end group 
end object 


First, 16 vectors are defined, each of which is used to build one vertex (control point). Next, 
a surface is defined that uses basis bez3 for both the U and V parameter directions. Since the 
surface is built from only one 4 x 4 Bézier patch, the parameter vector after the basis range has 
only length 2. If there had been two patches in the U direction and three in the V direction, the 
bases would have been referenced as 


1.0 


"bez3" OQ. , 
3333 0.66667 1.0 


5 
"bez3" OQ. 3 


by changing the parameter range of the basis. This has no influence on the geometry of the surface, 
but generates UV texture coordinates in a different range (here, [0.0,2.0] x [0.0,3.0]). However, 
a different parameterization does affect the texture surface range (see below), and the range of 
trimming, hole, and special curves (which do not define their own ranges but borrow the range 
from the surface they apply to). 
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The optional surface_specials_list that completes the surface definition is a sequence of trimming 
curves, hole curves, special curves, and special points as described in the next section. 


2.7.10.3 Surface Derivatives 


mental ray can automatically generate surface derivative vectors if requested. First derivatives 
describe the UV parametric gradient of a surface; second derivatives describe the curvature. 
They are computed and stored only if requested by derivative_request statements in the surface 
definition: 


derivative number, [numberin | 


There can be one or more derivative statements that request first and/or second derivatives. 
Valid values for number are 1 and 2, for first and second derivatives, respectively. 


mental ray does not use derivative vectors but makes them available to shaders. First derivatives 
are presented as two vectors (dSdu and dSdv, with S being the surface and the derivatives evaluated 
at the current point in parameter space); second derivatives are presented as three vectors (d*Sdu’, 
d*Sdv*, and d?Sdudv). This is the same format that can be explicitly given for polygonal data 
using the d keyword in vertices. Surfaces always compute the vertex derivatives analytically, 
explicit vertex derivatives given by d keywords are ignored. 


2.7.10.4 Texture Surfaces 


A plain surface statement defines the geometry of the surface. If a texture is to be mapped on 
the surface, it is necessary to include texture surfaces. A texture surface defines a mapping from 
raw UV coordinates to texture coordinates as used by shaders. A vector texture is a variation of 
a texture surface that additionally defines a pair of basis vectors; it is used for bump mapping. 


The texture or vector texture directly following a surface defines texture space number 0, the next 
defines texture space number 1, and so on, exactly like the first t statement after the v statement in 
a vertex used for building polygonal geometry defines texture space number 0, the next t defines 
texture space number 1, and so on. Basically, texture and vector texture surfaces replace the t 
statements used by polygonal geometry, because attaching textures to control points that usually 
are not part of the surface is not useful. 


Texture spaces is what ends up in the state — tex_list array where it can be accessed by texture 
shaders to decide which texture is mapped which way. Texture space 0 is the first entry in that 
array, which is used by the shader for the first texture listed in the texture list in the material 
definition. In general, there is one texture space per texture on a material, although shaders making 
nonstandard use of texture spaces could be written. 


The syntax for texture surfaces is a simplified version of geometric surfaces. The texture_surface_ 
list in the grammar summary at the beginning of the “Surfaces” section above expands to zero or 
more copies of the following block: 


2.7. Scene Entities 143 


[ volume | [ vector ] texture 
"u_basis name" u_param_list 
"v_basis name" v_param_list 
vertex_ref_list 


Unlike geometric surfaces, no surface name and material name is given. Bases are given like in 
geometric surfaces. Texture surfaces use the ranges of the geometric surface they are attached to, 
they are not repeated in the texture surface basis statements. The vertex_ref_list follows the same 
rules as the geometric surface’s vertex_ref_list. Texture surfaces have no specials such as trimming 
curves or holes. 


The optional volume keyword in the texture surface definition disables seam compensation. It 
should be used for 3D textures where each texture vector should be used verbatim. If the volume 
flag is missing, the tessellator detects textures that span the geometric seam on closed surfaces, 
and prevents rewinding. Consider a sphere with a 2D texture that is shifted slightly in the U 
parameter direction: a triangle might have uw = 0.0 on one side and uw; = 0.1 on the other side. 
If the texture is shifted towards higher u coordinates by 0.05, up and w; will map to texture 
coordinates to = 0.95 and t; = 0.05, assuming an otherwise normal UV mapping. Even though 
Uo < 41, to >> t1, causing a fast “rewind” of the texture. Seam compensation corrects t; to 1.05. 
This is undesirable for 3D textures, which should have the volume keyword set. Most problems 
with strangely shifted textures are caused by inappropriately used or missing volume keywords. 


The optional vector keyword in the texture surface definition is a flag that causes bump basis 
vectors to be calculated during tessellation. This flag must be used if the texture surface is used 
for a bump map that expects to find bump basis vectors in the geometry. However, this is an 
extremely rare requirement — none of the standard shaders (base, physics, and contour) or any 
standard modeling tool integration shaders require base shaders, so automatic bump basis vector 
generation is largely obsolete now. It was originally introduced for Wavefront compatibility. 


This is an example for the simplest of all texture surfaces, a bilinear mapping: 


object "mysurface" 
visible 
basis "bezi" bezier 1 
basis "bez3" bezier 3 


group 

# ... 16 vectors used for the surface 

9.0 O.0 0.0 # vector number 16 
U.0 2.0 0,0 # vector number 17 
1.0 8.0 0.0 # vector number 18 
1,0 14.9 0.0 # vector number 19 
# 16 vertices used for the surface 
v 16 # vertex number 16 
vy if # vertex number 17 
vy is # vertex number 18 
v 19 # vertex number 19 
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surface "surfi" "material" 
"bez3" 0.0.4.0 0.0 1.0 
"bez3" 0.0 1.0 0.0 1.0 
0123456789 10 11 IZ 13 14 15 


texture 
"bez1i" 0.01.0 
"bez1i" 0.0 1.0 
ig if 18 19 
end group 
end object 


This texture surface defines a bilinear mapping from the UV coordinates computed during surface 
tessellation to the texture coordinates. To define other than bilinear mappings, the texture surface 
needs to have more control points than just one at every corner of the surface. Whenever the 
surface tessellator generates a triangle vertex, it uses the UV coordinate of that vertex to look 
up the texture surface and interpolate the texture coordinate from the nearest four points of the 
texture surface. The resulting texture coordinate is stored with the vertex and becomes available 
in state — tex_list when the material shader is called because a ray has hit the surface. 


If more than one texture surface is given, one texture coordinate is computed for each texture 
surface and stored in sequence in the generated triangle vertices. Each texture surface is said to 
define a “texture space”. They are available in the state — tex_list array in the same order. The 
number and order of texture surfaces should agree with the number and order of textures given 
in the texture list in the material definition. (Note that not all material shaders support multiple 
textures.) 


If the material name of a surface is empty (two consecutive double quotes), the surface uses the 
material from the closest instance (this is called material inheritance). 


2.7.10.5 Curves 


Curves are two-dimensional parametric curves when they are referenced by surfaces. They are 
used as trimming curves, hole curves, and special curves. They must be defined before the surface 
which references them. Curves are three-dimensional parametric curves when referenced by space 
curves. A curve is defined as: 


curve "curve_name" "basisname" 
parameter_list 
hom_vertex_ref_list 
[ special special_point_list | 


The parameter_list of a curve is a list of monotonically increasing floating-point numbers that 
define the number of segments of the curve and the number of control points. Curve parameter 
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lists work very much the same way as surface parameter lists except that no range needs to be 
provided, because they are supplied by the surfaces that reference the curve under consideration 
as explained in the next section. For details on parameter lists, see the sections on bases and 
surfaces above. 


Each vertex reference in the hom_vertex_ref_list is an integer index into the vertex list of the 
current group in the object (index 0 is the first vertex), optionally followed by the keyword w 
and a weight value. (For backwards compatibility, the w keyword may be omitted if the weight is 
a floating-point value containing a decimal point.) Weights are used only if the curve is rational, 
they are ignored otherwise. If a weight in a rational curve is missing, it defaults to 1.0. The vertices 
indexed by the integers in the hom_vertex_ref_list should have no normals or textures (no n and 
t statements), and the third component of the vector (v statement) should be 0.0 because curves 


are defined in UV space, not 3D space. 


The optional special_point_list specifies points that are included in the approximation of the curve. 
After the special keyword, a sequence of integers follows that index into the vertex list, just like 
the integers in the hom_vertex_ref_list. The first component of the vector is used as the t parameter; 
it forces the point on the curve at parameter value t to become part of the curve approximation. 
Of course t must be in the range of parameters allowed by the surface definition. 


2.7.10.6 Trimming, Hole, and Special Curves; Special Points 


A surface may reference curves to trim the surface, to cut holes into it, and to specify “special 
curves” that become part of the tessellation of the surface. Special points in surfaces work like 
special points in curves, except that they provide a point in the parameter range of the surface, 
that is, a two-dimensional UV coordinate, rather than a one-dimensional curve parameter. They 
specify single points on the surface that are to be included in the tessellation. As all curves and 
points are in UV space, the third component of the vectors provided for them is ignored. None 
of the above types of curves and points may exceed the range of (0.0, 1.0) at any point. 


No two curves may intersect each other, and no curve may self-intersect. This is an important 
point because trimming curves and holes that are not closing or intersecting themselves or other 
loops can produce unexpected tessellation results. 

Trimming, hole, and special curves and special points are defined at the end of the surface 
definition. The curves are composed of segments from the list of curves of the surface’s group. 


The surface_spectals_list given in the previous section is a list of zero or more of the following 
four items: 


trim "Curvename" min max 
hole "Curvename" min max 
special "curve_name" min max 


special verteXjn; 
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The dots indicate that each trim, hole, and special statement may be followed by more than one 
curve segment or vertex, respectively. All listed segments are concatenated to form a single curve. 


The vertex integers specify vertices from the vertex section of the current group in the current 
object. Such a vertex specifies the UV coordinate of the special point that is to be included in the 
tessellation. 


Each of the three types of curves references a curve that has been defined earlier with a curve 
statement. If a single trim, hole, or special statement is followed by more than one curve, the 
resulting trimming, hole, or special curve is pieced together by concatenating the given curves. 
The min and max parameters allow using only part of the curve referenced. min and max must 
be in the range of the parameter vector of the curve which in turn must be mapped into the 
parameter range of the surface. The mim and max parameters of two different curve pieces are 
independent, they only depend on the curve parameter lists. For example, a trimming curve can 
be built from two curves, using the first three quarters of the first curve and the last three quarters 
of the second curve: 


curve "trimi" 
“pezi™" 0.0 1.0 2.0 3.0 4.0 
01234 


curve "trin2” 
"bez" 0.0 1.0 2.0 
o De 


surface "patchi" "mtl" 
"bez3" 0.0 1.0 0.0 
"bez3" 0.0 1.0 0.0 
& 7 8&8 10 71 12.45 14 15 16 17 18 19 20 21 
trim "trimi" 0.0 3.0 
"trim2" 0.5 2.0 


1.0 
Bee 


Both trimming curves use the basis bez1, which is assumed to be a degree-1 linear curve. Hence, 
trim1 connects the UV vertices 0, 1, 2, 3, and 4 with straight lines, and trim2 connects the vertices 
3, 5, and 0. If these two curves are put together by the trim statement in the surface definition, 
all parts of the surface that fall outside the polygon formed by the UV vertices 0, 1, 2, 3, and 5 are 
trimmed off. The trim2 curve includes vertex 0 to close the trimming curve. Holes and special 
curves are constructed exactly the same way. Trimming curves and holes must form closed loops 
but special curves are not restricted in this way. 


Note that trimming and hole curves must be listed in the correct order, outside in. If there is 
an outer trimming curve, it must be listed first, followed by the holes. If a hole has a hole, the 
inner hole must be listed after the outer hole. Since curves may never intersect, there is always 
an unambiguous order — if a curve A encloses curve B, A must be listed before B. Curves that do 
not enclose one another can be listed in any order. 
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This example omits the vector and vertex parts of the group in the object. Here is an example that 
defines a complete object containing a surface with a trimming curve that precisely follows the 
outer boundary. A trimming curve that follows the outer surface boundary does not actually clip 
off any part of the surface, but it is still useful if surfaces are to be connected, because connections 


work on trimming curves. 


object "mysurface" 


visible 
basis "bezi" bezier 1 
basis "bez3" bezier 3 
group 
# ... 16 vectors used for the surface 
0,0 8.0 G0 # vector number i6 
1.0 [2.0 0.0 # vector number 17 
Lee ot © # vector number 18 
0.0 5 220-, 9.0 # vector number 19 
# ... 16 vertices used for the surface 
v 16 # vertex number 16 
v 17 # vertex number 17 
v 18 # vertex number 18 
v 19 # vertex number 19 
curve "trimi" 
"pezi”"' O.0 U.20o 0.5 0.75 1.0 
to 2 Ae ee ss 
surface "surfi" "material" 
trim “trami” o.0. 1. 
end group 
end object 


The trimming curve in the example is linear, using a degree-1 Bézier basis. This means that the 
parameter vector has five equally-spaced parameters, one for each corner in counter-clockwise 
order and back to the first corner to close the trimming curve. Trimming and holes always require 
a closed curve or sequence of curves (they can be pieced together by multiple curves as long as 
the pieces form a closed loop together). The results are undefined if trimming or hole loops are 
not closed, or intersect. 


If the trimming curve would be a degree-3 Bézier going through four corner points, a parameter 
vector with 3-5 + 1 = 16 parameters would be required (again, the 5 is the number of corners 
visited including the return to the first to close the curve). 


For details on the parameter vector following the basis name in the definition of the curve, refer 
to section 2.7.10.5. The bases and parameter vectors for curves and surfaces follow the same 
rules, except that curves have no explicit range; they always use the implicit range given by the 
parameter list. 
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2.7.10.7_ Connections and Edge Merging 


Free-form surfaces may be connected to each other using the connect statements, respectively. 


The connect statement is “manual” in that it requires an explicit specification of the parts of two 
surfaces to be connected. These parts refer to intervals of trimming curves or hole curves of these 
surfaces, see section 2.7.10.5. A connection is defined as: 


connect "surface name, " "curve name," min, max 
"surface name " "curve name" miny max? 


This statement closes the gap between two surfaces surface_name, and surface_namez by 
connecting their trimming curves curve_name, and curve_name2. The curves are connected only 
in the range (min, ...max,) and (minz...max2), respectively. They share the same points, but 
normals, textures etc. are evaluated on the individual surfaces. Only surfaces that have trimming 
curves can be connected by an explicit connect statement. Trimming curves used in connections 
must satisfy three conditions: 


e As always, the trimming curve or sequence of trimming curves must be closed. 


e It does not matter whether the trimming curve is oriented clockwise or counterclockwise, 
but if a sequence of trimming curves is used all pieces must have the same direction. 


e The trimming curves along the connected range must run in the same direction in 3D space. 


The range values min, and max; must not exceed the range of the trimming curve segment as 
referenced by a trim statement of the corresponding surface. The minimum value must be less 
than the maximum value; it is not possible to satisfy the third condition by inverting the range. 


Best results are obtained if the curves to be connected are close to each other in world space 
and have at least approximately the same length. The connect statement is not meant to be a 
replacement for proper modeling. For carefully modeled surfaces these techniues will not be 
necessary most of the time. Their purpose is to close small cracks between adjacent surfaces that 
are already not too far from each other. Topologically complex situations with several connections 
meeting in a point are beyond its scope. 


2.7.11 Space Curve Geometry 


Unlike trimming curves, space curves are defined in 3D space. A space curve object may not 
contain any other type of geometry, such as free-form surfaces or polygons. Space curves are not 
rendered but serve as input geometry for modeling operations, by passing the space curve object 
as a parameter to a geometry shader. The curve geometry is defined as a list of space curves, each 
referencing multiple curve segments. 
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An object containing space curve geometry follows this outline: 


object "object name" 
[tag label_number in; | 
[ basis list ] 
group 
vector list 
vertex list 
[ list of curves | 
space curve 
[ list of curve segment references | 
end group 
end object 


A single space curve definition follows this outline: 


Space curve "Curve name" min max 


The dots indicate that each space curve statement may be followed by more than one curve 
segment reference. The min and max parameters allow using only part of the curve referenced. 
min and max must be in the range of the parameter vector of the curve. 


Here is an example of a space curve object: 


object "myspacecurve" 
basis "bezier_1" bezier 1 


group 
0.40.4 1.2 
O58 Oe 1.2 
0.6 0.6 1.2 
0.4 0.6 1.2 
YTOYVYivs2vs 
curve "curvei" bezier_1 


Oe ds ae we Bs 
01230 
space curve "spi" 
"curvei" 0. 4. 
end group 
end object 
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2.7.12 Hair Geometry*! 


Hair support was introduced in mental ray 3.1. Rendering hair is a difficult problem for triangle 
rendering because the number of hairs is typically very large (hundreds of thousands or millions), 
and each hair has a very large bounding box that it fills poorly. For this reason, a new hair primitive 
was introduced that avoids this problem, and also has a highly optimized storage format that 
avoids the storage overhead for triangle hairs. Here is an example: 


object "“object_ name" 


[ visible [on| off] ] 
[ shadow [on|off] | 
[ shadowmap [on| off] }° 
[ trace [on|off] | 


[reflection [mode] ]°* 
[refraction [mode] ]°* 
[ transparency [mode] ]|°* 


[ select [on | off] | 
[ tagged [on| off] | 
[ caustic [on|off] | 
[ globillum [on|off] | 
[ caustic [mode] | 


[globillum [mode] | 

[finalgather [mode] ]°* 

[ box [minx Min, min, MAX, Max, Max;] | 
[motion box [min, min, min; Maxx, Max, mMaxz] | 
[max displace value | 


[ samples min max |°"! 
[ data null |"data_name" | 
[ tag label_numberin; | 
hair 

[ material "material name" | 

[ radius radius | 

[approximate segments | 

[ degree degree | 

[max size size | 

[max depth depth | 

[hair n | 

[hair m hm ] 

[hair t ht | 

[hair u hu | 

[hair radius | 

[ vertex n | 

[ vertex m vm | 

[ vertex t vt | 

[ vertex u vu | 


[ vertex radius | 
scalar [ nscalars ] 
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scalar list 
hair [ nhairs ] 
hair offset list 
end hair 


end object 


The object header is similar to the headers for all other geometry types, but the standard 
group...end group block is replaced with hair...end hair. This block begins with a common header, 
followed by a scalar list, followed by a hair list. The header has the following optional statements: 


The material specifies the material to use when shading a hair. It is shared by all hairs in 
this object. If missing, the material is inherited from the instance. 


The radius specified the global radius of all hairs. This number may be overridden by hair 
or vertex radii if defined. It is defined in object space and typically a very small number. 


The default is 1. 


The approximate specifies the number of segments used to approximate each Bézier hair 
segment, if the degree is 2 or 3. The default is 1. 


The degree is the degree of the Bézier curves that approximate each hair. Valid values are 
1 (linear), 2 (quadric), or 3 (cubic). Each hair must have (1 + degree - segments) vertices, 
where the number of segments is a positive number. 


The max size defines the leaf size of the hair BSP tree that is created by mental ray to 
facilitate finding hairs during rendering. The default is 32. For a discussion of BSP trees, see 
the options block, which defines parameters for the BSP tree used for triangle intersection. 


The max depth defines the depth of the hair BSP tree. The default is 20. 


The hair n statement, if present, specifies that each hair has an associated normal vector 
consisting of three scalars. 


The hair m statement, if present, specifies that each hair has )m associated motion vectors 
consisting of three scalars each. 


The hair t statement, if present, specifies that each hair has ht associated texture scalars. 
The hair u statement, if present, specifies that each hair has hu associated user scalars. 


The hair radius statement, if present, specifies that each hair has an associated radius. No 
global radius may be present. 


The vertex n statement, if present, specifies that each vertex has an associated normal vector 
consisting of three scalars. If present, hair n is ignored. 


The vertex m statement, if present, specifies that each vertex has vm associated motion 
vectors consisting of three scalars each. If present, hair mis ignored. 


The vertex t statement, if present, specifies that each vertex has vt associated texture scalars. 
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The vertex u statement, if present, specifies that each vertex has vu associated user scalars. 


The vertex radius statement, if present, specifies that each vertex has an associated radius. 
No global radius may be present. If present, hair radius is ignored. 


The scalar list begins with the number of scalars that follow in angle brackets, followed by 
that many scalar values. 


The hair list begins with the number of hairs that follow plus 1 in angle brackets, followed 
by that many hair offsets. 


It does not make sense to specify hair nif there is also a vertex hair because all hair normals 
will be overridden. Similarly, if vertex radii are used, no hair radii (or the global radius) should be 
present. If any normals are specified, the hairs are not intersected like cylinders but like oriented 
flat ribbons. 


The scalar list defines a sequence of hairs. Each hair consists of a certain number of scalars that 
describe the entire hair, followed by another number of scalars that describe each vertex of the 
hair. The layout of these sequences of scalars is identical for all hairs, except that each hair may 
have a different number of vertices. It is not possible to have one hair with three texture scalars 
and another with two, for example. Here is the exact sequence of scalars for a single hair: 


e Header: 


{ If there was a hair n statement, three scalars for the hair normal (X, Y, Z). 
{ 4m motion scalars (X, Y, Z, X, Y, Z, ...). 

{ ht texture scalars. 

{ hu user scalars. 


{ If there was a hair radius statement, one radius scalar. 
e Vertices: 


{ Three mandatory scalars that define the location of the vertex in object space (X, Y, 


FAN 

If there was a vertex n statement, three scalars for the vertex normal (X, Y, Z). 
om motion. scalars (X,, Y, Z, 2. Vy 25 sa) 

vt texture scalars. 


vu user scalars. 


am 


If there was a vertex radius statement, one radius scalar. 


All vertices begin with three scalars for the location. The order of the other vertex scalars, and 
the order of the header scalars, is determined by the order of hair and vertex statements. The lists 
above correspond to the syntax listing at the beginning of this section: first n, then m, then t, then 
u, then radius. 
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Each hair has only one header but multiple vertices. As described above, the number of vertices 
must be (1 + degree - segments), where segments may be different for each hair. This number is 
not encoded in the hair but in the separate hair list. Note that hairs do not use texture vectors like 
polygons and free-form surfaces but texture scalars. It’s up to the shader to interpret state — tex_ 
list as a list of scalars, and properly use them in groups of one, two, three, or whatever is needed. 
This makes it possible to avoid the third null component if only two-component UV textures 
are needed, for example, which can save a lot of memory because hair objects tend to have a very 
large number of vertices, probably millions. 


The hair list specifies where in the scalar list each hair begins, by oftset in the scalar list such that 
0 is the first scalar, 1 is the second scalar, and so on. At the end of this offset list, one extra offset 
specifies the last scalar plus one, where the next hair would begin if there were another one. If 
all scalars are used (which is normally the case), the first offset is 0 and the extra one at the end 
equals the number of scalars. Here is a simple example for a hair object: 


object "hair1i" 
visible trace shadow 


tag 1 
hair 
material "mtl" 
radius 0.3 
degree 1 
baie & 2 
vertex t 1 
scalar [ 42 ] 
11 22 
0.0 0.0 0.0 1111 
0.0 1.0 O70 1112 
ed 10 O.0Lils 
33 44 
0.0 0.0 0.0 1114 
0.0 +10 0.0 1115 
ae =1 0 0.0: 1216 
55 66 
0.0 0.0 G,0 T1Lif 
7.0 =1.0 7.0 1126 
“io “4.0 0.0 1119 
hair [ 4 ] 
0 14 28 42 
end hair 
end object 


This example consists of three hairs, each with three vertices. The header of each hair consists of 
two texture scalars (11 22, 33 44, and 55 66, respectively). Each vertex consists of four scalars, 
three for the location in object space and one more for a vertex texture. The shader will receive 
three texture scalars, two from the hair and one more from the vertices. The former are copied 
from the hair that was hit, and the latter is interpolated from the nearest two vertices. They are 
stored in state — tex_list as if it were a scalar array, header texture scalars first, so the two hair 
texture scalars end up in tex_list{0].x and tex_list{0].y, and the vertex texture scalar ends up in tex- 
list{O].z. It is best to re-cast tex_list to a miScalar pointer in the hair shader. 
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Hair objects may use the same material shaders as any other object, but often special hair material 
shaders are used because although hair may be a cylinder, it is too thin for properly resolving 
the upper and lower edge and the diffuse terminator and the highlight. There is a simplified 
hair illumination shader in the base shader library, mib_illum_hair that implements a much more 
effective hair shading model. 


2.7.13, Subdivision Surface Geometry 


Subdivision surfaces are created by repeated refinement of polyhedral control meshes according 
to certain subdivision rules. The control mesh is basically a polygon mesh with certain restrictions 
(triangles and quads only) and certain extensions (for creases, for example), which is approximated 
more and more finely to generate a smooth limit surface. The limit surface obtained by this process 
is tangent-plane smooth at extraordinary vertices and curvature smooth at regular vertices. The 
main advantage of subdivision surfaces over NUBRS is their ability to define arbitrary topology 
geometry, that is, they do not require a rectangular parameter domain. 


Subdivision surfaces are available in mental ray as an optional product, called mental matter. 
Subdivision surfaces support can be added to mental ray either by linking the /zbmisubdiv.so in the 
same way a shader library is linked, or by using an integrated version of mental ray that combines 
mental ray and mental matter. The library implements approximation and management of 
subdivision surfaces, and has a powerful C++ API allowing multiresolution modeling operations. 
The .mi format allows definition of subdivision surfaces. For complex modeling operations 
geometry shaders using the above mentioned C++ PI can be written. This API comes with a 
separate documentation, see [CAPI2]. 


The subdivision surface implementation supports the Loop scheme, which operates on a control 
mesh consisting of triangles, and the Catmull-Clark scheme, which operates on a control mesh 
consisting of quads (polygons with four vertices). Face refinement is adaptive, supporting the 
LDA approximation criteria described in section 2.7.14. Vertices may have features assigned 
which modify the subdivision rules. Detail vectors may be specified for vertices on any level in 
the face hierarchy for multiresolution representation. Trim edges can be specified on any level to 
cut holes into the surface. Edges can be tagged as a crease with fractional sharpness to model for 
example wrinkle features. All these features are described in the following sections. 


Other features such as multiresolution modeling, approximation precision per face, face visibility, 
animation capabilities and NURBS export and import are not accessible from the .mi format. 
See [CAPI2] for details on these advanced modeling capabilities. 


Subdivision surface geometry, like polygonal geometry, is defined by a series of sections. An 
object containing only subdivision surface geometry follows this broad outline: 


object "object_name" 
.. # flags, boxes, data, etc. 
group 
vector list 
vertex list 
subdivision surface 
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... # more subdivision surfaces 
[ approximation list | 
end group 
end object 


The vector list in the group is a list of (x, y, z) vectors used for face vertex positions, detail vectors, 
texture and motion vectors. 


The vertex list that follows the vector list builds control vertices from the vectors. This works like 
the vertex list of polygonal geometry, except that no normals can be defined here. Here position 


vectors, texture coordinates and motion vectors can be referenced. 
Features may be associated with vertices by specifying either corner, conic, cusp, dart or 
smooth behind the regular vertex definition: 


vec-_ref [ tex_list | [ m motion_ref |[ corner [ level level ] ] 
vec_ref [ tex_list ][mmotion_ref |[ conic [level level ] ] 
vec_ref [ tex_list ][mmotion_ref|[ cusp [level level ] ] 
vec_ref [ tex_list ][mmotion_ref |[dart [level level ] ] 
vec_ref [ tex_list ] [ m motion_ref |[ smooth [ level level ] ] 


s$a090 9 4 


Here vec-_ref is the reference of a position or detail vector, tex_list is a list of texture coordinates 
with t keywords and corresponding coordinate indices, and motion_ref is an optional motion 
vector. Only one motion vector may be specified for each vertex with mental ray 2.1 and 3.0, and 
up to 15 with mental ray 3.1. 


The optional vertex feature follows, and an optional level can be specified if the feature is active 
on a level above vertex definition level. Texture coordinates may only be specified for base face 
level vertices. The vertex features are described in more detail in a separate section below. 


The subdivision surface geometry list consists of subdivision surface statements, much like 
Free-Form geometry consists of surface statements. For a description of vector lists and vertex 
lists, refer to page 130. 


The approximation statements are very similar to the free-form case, except that approximate 
surface is replaced by approximate subdivision surface. See section 2.7.14 for details. 
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2.7.13.1 Subdivision Surfaces 


A subdivision surface specifies a name and a list of optionally refined base faces, followed by 
optional derivative request: 


subdivision surface "surfacename " 
[ texture_interpolation | 
[ base_mesh | 
[ derivative_request | 

end subdivision surface 


Triangles and quads can be mixed in the same subdivision surface, but they may not share vertices. 
2.7.13.2. Base and Hierarchy Faces 


The base mesh of a subdivision surface is very similar to polygons. It uses the same syntax, but 
only faces with three or four vertices are allowed, since the Loop subdivision scheme operates 
on triangle meshes and and the Catmull-Clark scheme on quad meshes. The face vertices must 
be specified in counter-clockwise order, the mesh must be 2-manifold. 


p ["material_name"] vertex_ref_list 
[ crease crease-mask sharpness_list ] 
[ trim trim_mask | 


[ { hira-spec } ] 


The p keyword begins definition of a base face. An optional material name may follow, otherwise 
the material of the previous base face is assigned to the current base face. It the current object is 
marked as tagged, a label integer must be given instead of the material name (this is not shown 
here). Face vertices must be specified in the vertex_ref_list. 


The optional crease statement allows specification of crease edges. With crease_mask up to four 
edges are selected for crease, the floating point sharpness values follow in the sharpness_list. crease_ 
mask is a bitmap where crease edge indices are associated with corresponding bit positions in the 
mask. The diagram below shows the vertex and edge labeling of a base triangle: 
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The numbers inside the triangle indicate vertex numbers, the numbers at the three edges indicate 
the corresponding bit position in the crease bitmap. Bit 0 is assumed to be the least significant bit. 
Here is an example where edges 0 and 1 in a triangle should be crease edges, with corresponding 
sharpness values of 0.7 and 1.0: 


crease 3 0.7 1 


For quads the vertex and edge labeling is similar, as shown in this diagram: 


2 


For more information on crease edges, see section 2.7.13.4 below. A base face may be trimmed 
with the trim statement. The trim_mask is a bitmap where trim edges are selected according to 
their index in the face, in a way very similar to the crease bitmap described above. For more 
information on trim edges, see section 2.7.13.6 below. 


2.7.13.3. Face Subdivision 


It is possible to explicitly subdivide faces and to specify detail. The surface begins with a base 
mesh, which is subdivided into finer and finer levels, until the final smooth limit surface is reached. 
These levels form a hierarchy with the base mesh at its root. Modeling allows control over the 
levels of the hierarchy, such that the subdivision is guided by predefining how the subdivision 
takes place by predefining vertices on higher levels. This is useful to introduce local detail. For 
example, a head can be modeled by defining the general shape as the base mesh, and the nose can 
be introduced by defining one or more higher levels that introduce the required local detail. It is 
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sufficient to define higher levels only where detail is needed; it is not necessary to define all parts 
of a higher level. (This would very quickly require very large numbers of vertices, even where no 
detail is required.) 


Definition of detail on higher levels of the hierarchy is done by subdividing a face of the next-lower 
hierarchy level. High-level vertices can not be placed just anywhere, but only by subdividing a 
triangle or quad that already exists on the next-lower level, in a fixed way by dividing its edges. 


In the .mi scene language, a face is subdivided by specifying a pair of curly brackets around hira_ 
spec. Inside the hira_spec block a configuration of four children on the next level is selected, called 
a kit. The kit specification hira_spec is defined as: 


[ child child_index { hira_spec } ] 

[detail  detail_mask detail_list | 

[ trim child_index trim_mask | 

[crease  child_index crease-mask sharpness_Iist | 
[material child_index material_name |] 
[material child_index label 


In all the statements above, the child within the kit is selected with a child_index. A child may be 
further subdivided explicitly by specifying a hira_spec block inside curly brackets. The maximum 
number of subdivision levels that can be specified is 15. 


A detail vector specifies the offset to be added to the result of subdivision on a certain level for a 
certain vertex. The detail vector is specified in object coordinates, but is transformed using local 
reference frames. Adjacent subdivided faces automatically create a shared midpoint on the edge 
they share. A detail vector can be assigned using both faces, but a single assignment is sufficient 
since the vertex is shared. 


Detail vectors may be specified for the current kit vertices for the current subdivision level. A 
triangle kit has six vertices where detail vectors can be assigned, a quad kit has nine vertices. 
Detail vectors may be defined also on higher hierarchy levels above the current vertex definition 
level by explicitly subdividing the face and specifying details on the higher level kits. 


The same detail vector may be assigned to different vertices, even on different levels, since 
there is no relationship between the vertices in the vertex_list and the vertices that are created 
automatically for the limit surface. Here the detail vectors are simply looked up in the vector list 
and their value is assigned to internal subdivision surface vertices. 


Detail vertices for the current kit are selected with the bitmap detail_mask. Each vertex of the kit 
has a corresponding bit in the bitmap. The vertex labeling for a triangle kit is shown below: 
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Pe 
5 4 
0 3 1 
For a quad kit the labeling is similar: 
3 6 2 
Fs 5 
0 4 1 


The detail vectors are specified with the detail_list, which is a list of vertex indices. For example, 
if a detail vector is given by vertex index 10 and it should be assigned to the central vertex of a 
quad kit, one would have to specify 256 for the detail_mask, followed by 10. 


Crease edges on the kit subdivision level can be specified by selecting a child in the kit with child_ 
index, followed by an edge mask selecting the edges within that child, and finally followed by 
floating point values specifying the sharpness of the selected edges. 


Trim edges on the kit subdivision level can be specified by selecting a child in the kit with child_ 
index, selecting one of the four children, followed by an edge mask similar to the trim mask for 
base faces. 

Materials can be assigned to individual faces by using the material keyword, followed by a child 


index selecting the face within the kit, finally followed by the material name (or label index if the 
object is tagged). Materials are inherited in the hierarchy. 


2.7.13.4 Vertex Features 


Vertices may be tagged with the following features to modify the subdivision rules: 


e A conic vertex is interior, isolated and has no well defined tangent plane. The tip of a cone 
is an example. 
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e Atacusp vertex all approaching tangent vectors converge to a single direction. The tangent 
space at this point collapses to a line, like a rubber sheet pulled at a single point to become 
a needle-shaped tip. The cusp vertex is interpolated. 


e Atacorner vertex more than two crease or boundary edges are incident, the limit surface 
has no tangent plane at this location, and the vertex is interpolated. The surface is partitioned 
into smooth patches separated by the crease lines and converge at the corner vertex. 


e Ata dart vertex one or several crease lines terminate in a smooth vertex; the surface has a 
well defined tangent plane. 


e Ata smooth vertex no feature is defined. This is the default. 


2.7.13.5 Smooth Creases 


Creases are discontinuities introduced into the surface in oder to define sharp geometric details 
such as wrinkles. Crease edges may be specified for edges which are not on the geometric 
boundary. Connecting crease edges must be defined on the same level. 


A vertex with exactly two incident crease edges is internally marked as a crease vertex. Normal 
vectors for vertices on an infinite sharp crease line are not shared; instead, two normal vectors 
are created for the faces on each of the two sides on the crease line. A crease sharpness value of 0 
assigned to an edge will result in smooth subdivision, a value of 1 results will generate an infinite 
sharp crease, and fractional values between 0 and 1 will generate smooth creases. Sharpness values 
of subsequent higher subdivision levels are computed using a quadratic B-Spline function applied 
to the sharpness values of the parent edges. 


2.7.13.6 Trimming 


Trim edges may not be defined on the boundary or on crease edges. Connecting trim edges must 
be defined on the same level. Trim loops may not intersect or touch. Regions where faces are 
located inside a closed trim loop will generate a hole in the surface. It is not allowed to create trim 
regions within trim regions. It is legal to specify open trim loops, but here no holes are created in 
the surface. 


When vertex features must be defined for vertices on trim loops above level 0, one has to reference 
a vertex defining that feature. If this vertex does not have significant detail, a zero length detail 


vector must be referenced to satisfy the .mi grammar in the vertex section. 


At trim loops, boundary subdivision rules are applied. 
2.7.13.7 Derivatives 


mental ray can generate surface derivative vectors for subdivision surfaces if requested. They 
are computed and stored only if requested by derivative_request statements in the subdivision 
surface definition: 
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derivative numberin, [ spaceint | 


For number 1 must be specified, higher derivatives are not supported. Since subdivision surfaces 
allow arbitrary topology, there is no intrinsic surface parameterization available, so a texture 
space which defines orientation of the derivative vectors must always be specified with the space 
number. The first t vectors in the vertex definition is space 0, the second is space 1, and so on. 


2.7.13.8 Texture Space Interpolation 


Subdivision surface texture spaces can be created either using subdivision rules (interpolated 
between vertices, which is the default) or computed once per face, which linearly interpolates the 
texture coordinates within the face. The subdivision rule interpolated spaces will in general give 
a better mapping compared with the linear interpolation method. The interpolation method can 
be specified separately for each texture space with the optional texture interpolation statement: 


texture space [options] 
options is a comma-separated list of either face for linear interpolation or subdivision 
for subdivision rule interpolation. The first t texture vertex statement in the vertex section 


corresponds to the first entry in this array; the options list has one member for each t statement 
in each vertex. (All vertices must have equal numbers of t statements.) 


2.7.13.9 Example 


In the example below a cube base mesh is created, the four bottom level 0 edges are marked for 
infinite crease (1.0 for each edge), the top face is subdivided once and a detail vector is assigned 
to the central vertex on level 1. 


object "quadcube" 


group 

oot a a | 
lt aa 

1 ee On | 
-1 1.<1 
=i =. J 
a a 

1 1 1 
ct ee a | 

0 0 0.4 


yvOviv2v3v4v5v6vV7Vv8 

subdivision surface "surfi" 
po0i54 
pigzg6s 
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detail 256 8 
- 
p03 2i1 crease 151111 


end subdivision surface 
approximate subdivision surface angle 7 "surfi" 
end group 
end object 


2.7.14 Approximations 


Approximations are defined within an object group and they specify how previously defined 
polygons, surfaces, and curves should be tessellated. Within an object group containing free- 
form surface geometry the approximation statements are given separately for the surface itself 
and for curves used by the surface. The surface approximation statement sets the approximation 
technique for the surface itself. If it carries a displacement map this statement refers to the 
underlying geometric base surface and does not take the displacement into account. One 
may specify the approximation criteria on the displaced surface with an additional displace 
approximation statement or even leave out the surface approximation statement altogether. 


If the material of the surface does not contain a displacement shader the displace approximation 
statement is ignored. A trim approximation statement applies to all trimming, hole and special 
curves attached to the given surface or surfaces collectively; it is equivalent to separate curve 
approximations for each individual curve. When the keyword approximate is directly followed 
by an approximation technique it refers to a polygon or a list of polygons. It only has an effect 
on displacement mapped polygons. If the options statement specifies approximation statements 
for base surfaces and/or displacements, they override the approximation statements in the object. 
This can be used for quick previews with low tessellation quality, for example. 


flags approximate 
technique [ mining MaXint | 


flags approximate surface 
technique [ Minin, MaXinr | [| MAX MaXjn, | “Surface _name" ... 


flags approximate displace 
technique [ Mining MaXin, | “surface_name" ... 


flags approximate trim 
technique [ mining MaXin, | "surface_name" ... 


flags approximate curve 
technique [ Mining MAXin | "“Curve_name" ... 
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flags approximate space curve 
technique [ mining MaXin, | “Spacecurve_name" ... 


The dots indicate that there may be more than one surface_name or curve_name following the 
approximation statement. The given approximation is then used for all named surfaces or curves. 
The flags’ are explained in more detail in subsection 2.7.14.2 below. 


technique stands for one or more of the following: 


view 
offscreen 
tree 
grid 
fine 
delaunay 

[regular ] parametric u_subdiv [ v_subdiv ] 


363 


Sid 


[regular ] parametric u_subdiv% [v-_subdiv% |? 
any 
sharp sharp?! 


length edge 

distance dist 

angle angle 

spatial [view] edge 
curvature [view] dist angle 
grading angle 


tree, grid, fine, and delaunay are mutually exclusive. parametric cannot be combined with 
any of the others except grid, which is the default for the parametric case anyway. regular can 
only be used together with parametric. view has no effect unless one of length, distance, 
spatial, or curvature is also given. Grading can only be used in combination with Delaunay 
triangulation. 


View-dependent approximation is enabled if the view statement is present. It controls whether 
the edge argument of the length and spatial statements, and the dist argument of the distance 
and curvature statements, are in the space the object is defined in or in raster space. 


Normally geometry outside the viewing frustum is tessellated much more coarsely because it is 
not directly visible. However, in some cases it may become visible due to large flat mirrors, or is 
casting shadows on visible geometry. In these cases the of fscreen*” flag can be used to tessellate 
geometry outside the viewing frustum at the full accuracy. Note that this can generate very large 
numbers of triangles for things like large displaced ground planes very close to the camera. 


Tree, grid, and Delaunay approximation algorithms are available for surface approximation. 
The grid algorithm tessellates on a regular grid of isolines in parameter space; the tree algorithm 
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tessellates in a hierarchy of successive refinements that produces fewer triangles for the same 
quality criteria; Delaunay triangulation creates a successive refinement that maximizes triangle 
equiangularity. By definition parametric approximations always use the grid algorithm; all 
others can use either but tree is the default. tree, grid, and delaunay have no effect on 
curve approximations. Delaunay triangulation creates more regular triangles but takes longer to 
compute. 


Parametric approximation subdivides each patch of the surface into u_subdiv -degree equal-sized 
pieces in the U parameter direction, and v_subdiv -degree equal-sized pieces in the V parameter 
direction. If regular the number of pieces the whole surface is subdivided into simply equals 
the parameter value; the number of subdivisions may also be specified as the percentage? of v- 
subdiv must be present for surface approximations and must be omitted for curve and trim 
approximations. Note that the factor is a floating point number, although a patch can only be 
subdivided an integral number of times. For example, if a factor of 2.0 is given and the surface is 
of degree three, each patch will be subdivided six times in each parametric direction. If a factor 
of 0.0 is given, each patch is approximated by two triangles. 


Curves are subdivided in subdiv - degree equal pieces by the parametric approximation and into 
subdiv equal pieces by the regular parametric approximation. 


For displacement mapped polygons and displacement mapped surfaces with a displace 
statement regular parametric has the same meaning as parametric in the approximation. 
For displacement mapped polygons the u_subdiv constant specifies that each edge in the 
triangulation of the original polygon is subdivided for the displacement 2”~”?4” times. If a 
displace approximation is given for a displacement mapped surface, the initial tessellation of the 
underlying geometric surface is subdivided in the same way as for polygons. For example, a value 
of 2 leads to a fourfold subdivision of each edge. Non-integer values for the subdivision constant 
are admissible. Nothing is done if the expression above is smaller than 2 (if u_subdiv < 1). The 
v_subdiv constant is ignored for the parametric approximation of displacement maps. 


Length/distance/angle (LDA) approximation specifies curvature-dependent approximation 
according to the criteria specified by the length, distance, and angle statements. These 
statements can be given in any combination and order, but cannot be combined with parametric 
approximation in the same approximate statement. If they are preceded by the any keyword the 
approximation stops as soon as any of the criteria is satisfied. 


The length statement subdivides the surface or curve such that no edge length of the tessellation 
exceeds the edge parameter. edge is given as a distance in the space the object is defined in, or as 
a fraction of a pixel diagonal in raster space if the view keyword is present. Small values such as 
1.0 are recommended. For tree and grid approximation the min and max parameters, if present, 
specify the minimum and maximum number of recursion levels of the adaptive subdivision. The 
min parameter is a means to enforce a minimal triangulation fineness without any tests. Edges are 
further subdivided until they satisfy the given criterion is fulfilled or the max subdivision level 
is reached. The defaults are 0 and 5, respectively; 5 is a very high number. mental ray imposes 
a hard maximum of 7; mental ray 3.3 and higher have no hard limit for displacement. Good 
results can often be achieved with a maximum of 3 subdivisions. For Delaunay approximation, 
the number max following the keyword max specifies the maximum number of triangles of the 
surface tessellation. This number will be exceeded only if required by trimming, hole, and special 
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curves because every curve vertex must become part of the tessellation regardless of the specified 
maximum. 


For displacement mapped polygons and displacement mapped surfaces with a displace 
approximation statement the length criterion in the approximation limits the size of the edges of 
the displaced triangles and ensures that at least all features of this size are resolved. Subdivision 
stops as soon as an edge satisfies the criterion or when the maximum subdivision level is reached. 
It cannot be ruled out that at an even finer scale new details may show up which would lead again 
to longer edges. This caveat about the potential miss of high-frequency detail applies also to the 
distance and angle criteria. 


The distance statement specifies the maximum distance dist between the tessellation and the 
actual curve or surface. The value of dist is a distance in the space the object is defined in, or a 
fraction of a pixel diagonal in raster space if the view statement is present. As a starting point, 
a small distance such as 0.1 is recommended. For tree and grid approximation the min and max 
parameters, if present, specify the minimum and maximum number of recursion levels of the 
adaptive subdivision. For Delaunay approximation, the number max following the keyword max 
specifies the maximum number of triangles of the surface tessellation. 


For displacement mapped polygons and displacement mapped surfaces with a displace 
approximation statement the distance criterion cannot be used in the same way because the 
displaced surface is not known analytically. Instead, the displacements of the vertices of a triangle 
in the tessellation are compared. The criterion is fulfilled only if they differ by less than the given 
threshold. Subdivision is finest in areas where the displacement changes. For example, if a black- 
and-white picture is used for the displacement map the triangulation will be finest along the 
borders between black and white areas but the resolution will be lower away from them in the 
uniformly colored areas. In such a case one could choose a moderately dense parametric surface 
approximation that samples the displacement map at sufficient density to catch small features, 
and use the curvature-dependent displace approximation to resolve the curvature introduced 
by the displacement map. Even if the base surface is triangulated without adding interior points, 
as if its trim curve defined a polygon in parameter space, it is still possible to guarantee a certain 
resolution by increasing the min subdivision level. Only the consecutive subdivisions are then 
performed adaptively. 


The angle statement specifies the maximum angle angle in degrees between normals of adjacent 
tiles of a displaced polygon or the tessellation of a surface or its displacement or between tangents 
of adjacent segments of the curve approximation. Large angles such as 45.0 are recommended. For 
tree and grid approximation the min and max parameters, if present, specify the minimum and 
maximum number of recursion levels of the adaptive subdivision. For Delaunay approximation, 
the number max following the keyword max specifies the maximum number of triangles of the 
surface tessellation. 


Spatial approximation as specified by a spatial statement is a special case of an LDA 
approximation that specifies only the length statement. For backwards compatibility, the 
spatial statement has been retained; it is equivalent to the length statement plus an optional 
view statement. 


Curvature-dependent approximation as specified by the curvature statement is also a special 
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case of LDA approximation, equivalent to a distance statement, an angle statement, and an 
optional view statement. The spatial and curvature statements can be combined, but future 
designs should use length, distance, and angle directly. 


Grading applies only to Delaunay triangulation controls the density of triangles around the 
border of the surface. It allows the density of triangles to vary quickly in a smooth transition 
between a finer curve approximation and a coarser surface approximation. The angle constant 
specifies a lower bound related to the degree of the minimum angle of a triangle. Values from 0.0 to 
30.0 can be specified. Small values up to 20.0 are recommended. The default is 0.0. When using high 
grading values it is recommended to specify a maximum number of triangles because otherwise 
high grading values might result in a huge number of triangles or endless mesh refinement. The 
purpose of this option is to prevent a large number of tiny triangles at the trimming or hole curve 
to abruptly join very large triangles in the interior of the surface. 


The sharp*! keyword controls the sharp approximation of normal vectors. If set to 0.0, mental 
ray uses the interpolated normal as specified by the base surface, modified by displacement if 
available. If the argument sharp is set to 1.0, mental ray will use the geometric normal for a faceted 
look. This is primarily useful in fine mode. mental ray 3.2 allows any sharp value between 0.0 
and 1.0; earlier versions distinguish only exactly 0.0 and 1.0. 


If no approximation statement is given the parametric technique is used by default with w- 
subdiv = v_subdiv = 0 for surfaces, or u_subdiv = 0 in the case of curves and polygons. 


The following exceptions apply to subdivision surfaces: 


e The displace approximation is ignored, and the regular approximation is used. Subdivision 
surfaces are refined during displacement in a single integrated pass, so the separation 
between base surface and displaced surtace does not apply. 


e There are no restrictions on the approximation techniques in fine mode. Any LDA mode 
may be used. 


2.7.14.1 Fine Approximations?’ 


Standard approximations as described in the previous section work under the assumption that 
as few triangles as possible should be used to approximate a surface to achieve a user-defined 
quality. mental ray 3.1 also supports a new approximation mode called fine approximation, which 
addresses the problem from a different angle: it is capable of efficiently expending very large 
numbers of triangles to faithfully approximate even very complex surfaces, especially displaced 
surfaces, without excessive memory consumption. 


This is done by reducing the granularity of mental ray’s cache manager. In mental ray 3.0, it 
operated on entire objects, which could become very large when tessellated. mental ray 3.1 
applies cache management to smaller units formed by splitting objects into smaller sets, which 
can be individually tessellated without excessive memory requirements. This is especially useful 
for extremely detailed displacement maps. 
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Fine approximations support a small subset of approximation techniques since the remainder 
exists only to trade off triangle counts vs. quality, which is no longer a problem for fine 
approximations: 


fine [ nosmoothing’* | 
[sharp sharp ]*'! 

[ view] length edge 
parametric u_subdiv v_subdiv 


The f ine keyword enables fine approximation. It can be used for polygon displacement, free-form 
surface displacement, subdivision surface displacement and free-form surface approximations, 
but not for curves. fine nosmoothing can be used for polygon displacement for turning off 
a smoothing procedure which is used by default during fine polygon displacement. As with 
standard approximations, the sharp keyword controls normal-vector calculations. If set to 0.0, 
mental ray uses the interpolated normal as specified by the base surface, modified by displacement 
if available; if set to 1.0, mental ray will use the geometric normal to achieve a sharp faceted look.° 


Fine approximation requires the choice of one of three techniques: 


e view length specifies that all triangles should be subdivided until they are smaller than 
edge pixel diagonals. The edge value is typically around 0.5, or 0.25 or even 0.1 for very 
high quality. This technique is recommended for all fine approximations. 


e length specifies that the triangle edge length should stay under edge units in the object’s 
object space. The edge parameter needs more careful tuning than in the view-dependent 
case, and very high values defeat the purpose of fine approximation. 


e parametric’ tessellates a free-form surface such that all microtriangles have the same size. 
This results in very regular meshes but is harder to optimize, and may use significantly 
more memory. 


This simplicity makes it very easy to control fine displacement, without the risk of accidentally 
creating billions of triangles until memory runs out, and without juggling a large number of 
temperamental displacement-mapping parameters. 


However, fine displacement critically depends on the specification of a cache size limit, because 
otherwise the fine tessellation results would not flow through the cache but accumulate until 
memory runs out. For this reason, mental ray 3.1 and higher has a default cache limit of 512 MB. 
This can be overridden with the -jobmemory (3.0, 3.1) or -memory (3.2) command-line option. A 
good choice is half the amount of physical RAM, or 500-800 MB on 32-bit machines, whichever 
is smaller. If the number is too large, the operating system may run out of virtual address space; 
if it is too small, mental ray will perform too many cache flush operations. 

>mental ray 3.1. supports only the two modes sharp 1.0 (faceted look) and sharp 0.0 (default); mental ray 3.2 and 


higher support any value between 0.0 and 1.0. 
6Parametric approximation is supported only for free-form surfaces and not for displaced geometry. 
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If fine is used to approximate displaced geometry, it is also important to specify a correct max 
displace value. This parameter specifies the maximum absolute scalar value a displacement shader 
may return and serves to give mental ray a hint of the maximum extension of the displaced object. 
It is measured in object space. This parameter is somewhat “sensible”: if chosen too large, it may 
affect rendering performance; if chosen too small, any larger values returned by a displacement 
shader will be clipped. mental ray issues a warning message if max displace is chosen too small 
and a greater value is returned by the shader during rendering, thus providing a way to adjust 
max displace optimally. mental ray relies on max displace exclusively; if accidentally left at the 
detault of zero, all displacement will disappear (with a warning message). 


Fine approximation cannot be used together with merging and connections. 


2.7.14.2 Flagged Approximations’ 


mental ray 3.2 allows flagged approximations. An object or instance may optionally prefix 
approximate statements with one or more of the flag keywords visible, trace, shadow, 
caustic, and globillum. The approximation then applies only if the object is hit by the 
corresponding ray or photon. If no flags are given, the approximation applies to all rays and 
photons, which is equivalent to specifying all five flags. For example, 


visible approximate fine view length 0.5 ... 
trace shadow approximate regular parametric 33... 
visible approximate displace fine view length 0.25 ... 


specifies that where the object is visible to primary rays, it will be fairly detailed (fine view 
length 0.5), but its reflections, refractions, and shadows are very coarse (regular parametric 3 
3). Visible displacements are even finer (fine view length 0.25). In particular, final gathering falls 
under trace, and will also be coarsely approximated. In this example, mental ray will tessellate 
the object twice, once for visible and once for trace shadow. Missing approximations, in this 
example for caustic and globillum, use the default parametric 0 0. The trace flag also applies to 
final gathering and probe rays (mi_trace_probe). 


The intended use is for simple stand-ins. If the scene contains many detailed visible objects, 
it is undesirable to use the same level of detail for trace objects to compute shadows or global 
illumination because those rays are far less coherent, and pull in far more objects into the geometry 
cache simultaneously. Hence, simpler stand-ins should be used. This can be done by specifying 
entire separate objects with visible and trace object flags, but it is simpler to use the same 
objects and applying the flags only to the approximations. 


Since low-resolution shadow and trace stand-in objects are usually a small distance offset from 
the high-resolution visible object, it is often useful to offset rays at least that distance away from 
the visible object, using mz_ray_offset in the shader. 
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2.7.15 Instances 


instance "name" 


"element" |geometry function 


[ hide onloff | 

[ visible on|loff | 

[ shadow on|loff | 

[ shadow mode }°* 

[ shadowmap on|off °° 

[ trace on|loff | 

[ reflection mode }>* 

[ refraction mode }°* 

[ transparency mode }>* 

[ caustic [ mode ]] 

[ globillum [ mode ]] 

[ finalgather [ mode ]]°* 

[ transform [ matrix ]] 

[motion transform [ matrix ]] 

[ face [ frontlback\both ]|°* 
[ motion off | 

[ override | 

[ material "material name" 

[ material [ "materialname"[, "material_name" ... |] ] 
[ approximate | approximation [ , approximation ... |] | 
[ tag labelin; | 

[ data [ "data_name" ]] 


[ (parameters) | 
end instance 


Instances place cameras, lights, objects, and instance groups into the scene. Without instances, 
these entities have no effect; they are not tessellated and are not scheduled for processing. An 
instance has a zame that identifies the instance when it is placed into an instance group (see below). 
Every instance references exactly one element element, which must be the name of a camera, a 
light, an object, or an instance group. If the instanced item is a geometry shader function, the 
scene element created by this special shader is actually used as the instanced item. 


The hide flag can be set to on to disable the instance and the element it references. This is useful 
to temporarily suspend an instance to evaluate a subset of the scene, without deleting and later 
recreating suspended parts. hide is off by default. 


The visible, shadow, shadowmap>”, trace, reflection’*, refraction’, transparency”, 
caustic, globillum, finalgather’*and face flag’*modes are inherited down the scene 
DAG. Flags in instances lower (closer to the objects) override flags in instances higher up. 
The flags from the instance closest to the object are merged with the corresponding object flags. 
The resulting values become the effective flags for rendering. If no flags are specified in the 
relevant instances, only the object flags are used. For the exact definition of these flags refer to 
the Object section. The caustics mode bitmap contains six bits, and the desired behavior is the 
sum of: 
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1 to enable caustic casting, 


to enable caustic receiving, 


-_ WN 


to disable caustic casting, 
8 to disable caustic receiving, 
16 to enable interaction of caustic photons with the geometry, and 


32 to disable interaction of caustic photons with the geometry. 


Obviously, 1 and 4, 2 and 8, and 16 and 32 cannot be mixed, respectively. If mode is omitted, the 
default is 3 (enable casting and receiving). The fifth and sixth bits control “invisibility to photons”, 
that is, if visibility is disabled photons do not intersect this object and fly right through. This also 
affects the portion of the scene where photons have an effect and will be traced by mental ray. 
For example, if caustics occur only in a small part of the scene, objects outside that area should 
be made invisible to caustic photons to tell mental ray it should not waste time tracing photons 
there. The globillum mode bitmap works the same way and has the same bit layout, but controls 
global illumination instead of caustics. 


The reflection, refraction, transparency and finalgather bitmaps contain four bits: 


1 to enable casting 
2 to enable receiving 
4 to disable casting 


8 to disable receiving 


The transform statement is followed by 16 numbers that define a 4 x 4 matrix in row-major 
order. The matrix establishes the transformation from the parent coordinate space to the object 
space of the instanced element. If the instance is directly attached to the root instance group (see 
below), the parent coordinate space is world space. For example, the following matrix translates 
the instanced element to the coordinate (x, y, z): 


transform 


St OrRO 
N F&F O O 
+ CO O O 


i. 
0) 
0 


Note that “casting” here means “cast a shadow” or “cast a reflection” (that is, become visible in 
reflecting objects). This is the opposite sense of “casting a ray”. A material shader attached to an 
object can send out reflection rays only if the object has the reflection receive flag set (or inherits 
it). 
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Instance transformations are ignored if the options element explicitly sets the coordinate space 
to camera space, using the camera space statement. This is not recommended. The parent-to- 
local space transformation direction has the effect that in order to move an instanced object one 
(local) unit in the (local) +X direction, x must be decremented by 1. 


The motion transform matrix specifies a transformation from parent space to local space for 
motion blurred geometry. If not specified, the instance transformation is used for the motion 
blur transformation. In this case the parent instance determines whether motion blur is active 
or not. Motion blur is activated by specifying a motion transformation in the scene DAG. 
This transformation is propagated through the scene DAG in the same way as the instance 
transformations. The motion off statement turns off all motion information inherited up to this 
point, as if the camera and all instances above did not have motion transforms. This can be used to 
disable motion transformations for a scene subtree. The motion steps*! option in the options 
block controls the number of segments of the curved motion path resulting from evaluating the 
transformation at different times in the interval 0..1. 


If a motion transformation is specified in an object instance, the triangle vertex points of the 
tessellated geometry are transformed by the matrix product of the accumulated instance matrix 
and the inverse accumulated motion transformation matrix. The difference vector between the 
transformed and the untransformed triangle vertex point is used as a motion vector in local object 
space. If an object has motion vectors attached to the vertices, the motion vector calculated as 
described above is combined with the object motion vector. A motion transformation can be 
given for both object and camera instances. If a motion transformation is specified in a camera 
instance, the effective motion transformation for the triangle vertices is the matrix product of the 
relative instance and relative camera motion transformation. 


The override keyword is a prefix for material and approximate?” statements. It causes the 
material, material list, or approximation list to override the materials and approximations in 
instances and objects lower in the tree. Without overriding, lower instances and objects take 
precedence. 


The material name is the name of a previously defined material. It is stored along with the 
instance. Instance materials are inherited down the scene DAG. Materials in instances lower 
in the scene DAG (closer to the leaves) override materials in instances higher up. The material 
defined lowest becomes the default material for any polygon or surface in a geometrical object 
that has no material of its own. 


If a bracketed, comma-separated list of material_names is given, mental ray will use the n-th 
material in the list if the polygon or surface label is 7. If the label exceeds the length of the list, the 
first material in the list is used. Polygon and surface labels can be specified in the object definition 
that have the tagged flag set. If this flag is not set, the first material in the list is used. The list 
may not be empty. 


The approximation list°?* provides default approximations for objects. It isa comma-separated list 
of approximation statements, including displacement approximations, and all flags*? if applicable 
(visible, trace, shadow, caustic, globillum). See page 162 for syntax details. Like approximations 
in options blocks, the surface name must be all. For example, this approximation list overrides 
all approximations in the subtree below the instance, such that visible objects are tessellated 


172 2 Scene Description Language 


moderately fine, traced and shadow objects are very coarse, and visible displacements are very 


detailed: 


override approximate [ 
visible approximate fine view length 0.5 all, 
trace shadow approximate regular parametric 3 3 all, 
visible approximate displace fine view length 0.25 all 


A label integer can be attached to an instance using the tag statement. Labels are not used by 
mental ray in any way, but a shader can use the mi_query function to obtain the label and perform 
instance-specific operations. 


Also, user data can be attached with a data statement. The argument must be the name of a 
previously defined data element in the scene file. If the argument is missing, a previously existing 
data reference is removed. 


An instance may define parameters. Instance parameters are evaluated during scene preprocessing 
during preprocessing. Whenever the initial scene traversal finds an instance, it calls the inheritance 
function defined in the options element with the parent instance parameters and the parameters 
of the new instance. The inheritance function must then compute a new parameter set, which 
becomes the parent parameters for any future instances found in the element subtree below the 
new instance, if element is an instance group (if not, no sub-instances can exist and recursion 
ends). The inheritance function is also called if there is no parent instance yet or if the new instance 
contains no parameters. The final parameter set created by the inheritance function called for the 
bottom-level instance (which instances a camera, light, or object) is made available to shaders, in 
addition to the regular shader parameters. 


mental ray 3.1.2 introduces traversal functions in the options block, which are called like 
inheritance functions but have more control over the inheritance process. For example, they 
can control not only instance parameters but also flags, materials, and transformation matrices. 


The instance parameters must be declared just like shader parameters. The declare command 
must name the inheritance function, as specified in the options element. All instances share the 
same declaration. Note that this limits the portability of the scene — it is difficult to merge it 
with another scene that uses a different parameter inheritance function. 


If transform, motion transform, and material are given without arguments, the respective 
feature is turned off. This is useful for incremental changes. It is not relevant for the initial 
definition because these features are off by default when an instance is created. 


The element may be named in more than one instance. This is called “multiple instancing.” If 
two instances name the same object, the object appears twice in the scene, even though it is 
stored only once in the scene database. This greatly reduces memory consumption. For example, 
it is sufficient to create one wheel object for a car, and then instance it four times. Each of the 
four instances will contain a different transformation matrix to place the wheels in four different 
locations. (This implies that multiple instancing is not useful in camera space mode because in 
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this mode the transformations are ignored.) It is also possible to apply multiple instancing to 
object groups to replicate entire sub-scenes. 


If the instanced item is a “geometry shader”, the function is called with shader parameters and 
the scene element created by the shader is defined in the local coordinate space of the instance. 
The geometry shader is called just before tessellation takes place. The following example uses a 
geometry shader mib_geo_sphere: 


instance "sphere" 
geometry "mib_geo_sphere" () 
end instance 


This example creates a spherical object procedurally. It uses the syntax for anonymous shader; as 
usual the named shader syntax using the shader keyword and named shader assignments using 
the “=” sign can also be used. As usual, shader lists may be used; if the shader is correctly written 
all created objects are put in a group and instanced together. Named shaders created inside or 
outside procedural object definitions are in global scope and can be shared with other objects. 


For a complete example for building scene graphs with instances and instance groups, see below. 


2.7.16 Instance Groups 


instgroup "name" 
"name" 
[tag labelin, | 
[data [ "dataname" ]] 


end instgroup 


Instance groups, together with instances, provide the structure from which scenes are built. The 
scene is anchored at a root instance group, which contains instances referencing objects, cameras, 
lights, objects, and/or other groups. In the simplest case, all cameras, lights, and objects can be 
collected into a single group, forming a “flat scene” because there is no hierarchy. Cameras, lights, 
and objects are never put into an instance group directly. Instead, an instance must be defined, 
one for each element, and the instance is then put into the group. (This is why it is called an 
“instance group.”) 


Instance groups can be nested. An instance group is placed into a parent instance group exactly 
like a camera, light, or object: an instance must be defined for the child instance group, and the 
instance is put into the parent instance group. As with other entities, it is possible to create more 
than one instance for an instance group; this allows multiple instancing of sub-scenes. There is 
no limit on the nesting depth of instance groups. 


Since the only purpose of instance groups is as a container for instances, the syntax is very simple. 
After the name of the instance group, one or more names of instances follow. An incremental 
change to an instance group clears the old instance list (without deleting the instances themselves); 
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to add or remove an instance in an instance group, the incremental change must respecify the 
entire instance list. 


The top-level instance group has no instance. It is called the root instance group. The root instance 
group stands for the entire scene. It is passed to the render command to process the scene. More 
than one root instance group can exist, but only one can be processed at a time. Camera instances 
must always be attached to the root instance group, not a lower-level instance group, and it may 
not be multiply instanced to ensure unambiguity. Multiple cameras can exist in the root instance 
group, but only one can be passed to the render command. 


A label integer can be attached to an instance group using the tag statement. Labels are not used 
by mental ray in any way, but a shader can use the mi_query function to obtain the label and 
perform light-specific operations. 


Also, user data can be attached with a data statement. The argument must be the name of a 
previously defined data element in the scene file. If the argument is missing, a previously existing 
data reference is removed. 


mental ray 3.3 and later also supports groups that contain instances of lights to be used like 
lights, for example in the shader interface. This makes it possible to to put a set of lights into a 
group, and then treating the whole group like a single light for the purpose of shading. The mz_ 
sample_lght and related shader interface functions accept instances of light groups as if they were 
instances of lights. Light groups contain instances of lights, where the instances contain identity 
transformations. 


2.8 Contours 


In order to render the contour examples in this section, it is necessary to link with the contour.so 
shader library, and a $include <contour.mi> statement is also needed. The file contour.mi 
contains declarations of the contour shaders in contour.so. (Of course, contour shaders are 
fully programmable, so the possible contour modes are not limited to the examples described 


here.) 


Also, the contour store shader has to be specified in the options statement. A contour store 
shader has no parameters and is specified as 


contour store "contour_store_function" () 


2.8.1 Where To Place Contours 


A contour contrast shader specifies where there should be a contour. Like the contour store shader, 
the contour contrast function has to be specified in the options statement. The parameters of 
this function specify which difference in depth or surface orientation should cause a contour. 
For example, to get a contour where the difference in depth is more than 1.0 or the difference 
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in surface normal is more than 60 degrees and between materials, the following contour contrast 
shader is used 


contour contrast "contour_contrast function levels" ( 


"Zdelta" 130), 
"ndelta" 60.0, 
"diff_mat" on, 
"COntras.” on, 


"min level" 1, 
"max_level" 1 


(Be aware that if zdelta or ndelta is set to a very small value, contours will be created also in 
large regions interior to objects.) 


When diff-_mat is on, contours are created between different materials. When contrast is on, 
contours are created where the contrast between colors is larger than the contrast specified in 
the options within the options statement. The parameters min_level and max_level tell which 
levels of reflection and layers of semitransparent materials should have contours on them. When 
both are set to 1, as here, only the outermost materials get contours and no reflections cause 
contours. 


The hands in the figure show the influence the parameters of the contour contrast shader has 
on where contours are created. Top row (left to right): large zdelta and ndelta give only 
contours on the outline where the depth difference to the infinitely distant background is large; 
large ndelta and small zdelta give contours where there is even a small depth difference; small 
ndelta and zdelta gives contours where there is a small change in depth or orientation. Bottom 
row: Contours on deeper levels of materials seen through a semitransparent material; contours 
on reflections on a reflective material, for example the reflection of the thumb is visible in the 
index finger. 
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2.8.2 Color and Width of Contours 


The contour properties (color, width, etc.) depend on the object the contour is on and its material. 
For each material that should have a contour, one has to specify a contour shader. A material will 
not get a contour if it does not have a contour shader. The colors consist of four components: red, 
green, and blue color, and opacity. All four components of the color are normally between 0 and 1. 
The width is specified as a percentage of the minimum of image x resolution and y resolution. 
For example, if the image resolution is 700 x 500 and a contour width of 1.0 (percent) is specified, 
the thickness of the line becomes 5 pixels. The color, width, etc. can be parameters, or depend on 
curvature, distance, color, and illumination. 


A material gets a simple contour of constant color and width if it has the contour_shader_simple 
contour shader. For example, the following specifies red contours that are half a percent wide: 


contour "contour_shader_simple" ( 
Peaior” / <2. 0.0. 0,0. 7.0, # solid red 
“width” 0,5 # in % of image resol 


As another example of a contour shader, contours of color and width that are linearly interpolated 
between two values, depending on distance to the camera, are specified with the contour shader 
contour_shader_depthfade. Iwo depths, colors, and widths are specified. If a contour point is 
more distant than far_z, the contour gets color far_color and width far_width. If a point is 
nearer than near-_z, the contour gets color near_color and width near_width. If the depth is 
in between, the color and width are linearly interpolated. For example, to get contours that are 
interpolated between two percent wide red at depth —10 and half a percent wide blue at depth 
—25, specify 


contour "contour_shader_depthfade" 
"near_z" =—10..0, 
“near_color” 1,0 0.0 0.0 1.0. 
"near_width" 2.0, 
"Tar." = 200), 
"lar_color" O.0 O.0 1.0°1.0, 
"far_width" 0.5 


from this depth, 
color (red), 

and width (in %) 
to this depth, 
color (blue), 
and width (in %) 


+ HH HH FHM 


The left figure is a black-and-white illustration of this depthfade contour shader. The right figure 
is a scene with two materials with different contour type: illumination-dependent contours on 
the teapot and simple contours on the “floor”. 
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There are many other contour shaders in contour .so, and new ones can be written by the user. 


2.8.3. Contour Output 


After the regular image has been computed, a contour output shader can get the contour line 
segments and use them to for example render a contour image or write a file with contour 
information. The user can write contour output shaders using the built-in function mi_get- 
contour_line. 


There are three contour output shaders in contour.so. They can generate a contour image, a 
contour image composited over the regular image, and a PostScript file with black contours. The 
output shader has to be specified in the camera. 


To get a contour image called mycontourimage.rgb in rgb format, write 


output "contour,rgba" "contour_only" () 
output "rgb" "mycontourimage.rgb" 


To get an image called mycontourimage2.rgb (in rgb format) containing contours composited 
over the regular image, write 


output "contour,rgba" "contour_composite" () 
output "rgb" "mycontourimage2.rgb" 


The contour_composite output shader has two optional Boolean parameters: glow and maxcomp. 
The glow parameter makes all contours become darker and more transparent near their edges, 
creating a glow effect. maxcomp specifies that when a contour is over another contour, the 
maximum of the two colors (in each color band) should be used. If maxcomp is not specified 
(or set off), normal alpha compositing is used. The contour_only output shader also has the 
glow and maxcomp parameters, and in addition it has a background parameter which determines 


the background color (default is black). 
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To get a PostScript file called mycontourfile.ps with all contours in black, write 


output "contour,rgba" "contour_ps" ( 
"paper_size" 4, 
"paper_scale" Lis 
"paper_transform_b" 0.0, 
"paper_transform_d" 1.0, 


"title" on, 

"landscape" on, 

"ink stroke_dir" 1:0 1460 2.0, 

"ink min frac" 2 

"file_name" "mycontourfile.ps" 


The PostScript file in this example gives A4 paper size with full scale. "paper_size" 1s an integer, 
with 0 indicating “letter” size, 1 indicating “executive”, 2 indicating “legal”, 3-6 indicating 
“a3”, “a4”, “a5”, “a6”, 7-9 indicating “b4”, “b5”, “b6”, and 10 indicating “11x17”. The 
parameter paper_scale scales the PostScript output. Furthermore, the Postscript coordinates 


are transformed according to the matrix (5 1) where b and d are the parameters "paper- 


transform_b" and "paper_transform_d". This makes it possible to compensate for printers that 
print out with a slight skew. The Boolean title determines whether a title (consisting of file 
name and frame number) and a frame around the image are written. The Boolean landscape 
makes the output be in landscape mode rather than portrait mode. If the parameter ink_stroke_ 
dir is set, each contour segment will have a width that depends on its orientation, giving an ink 
pen look. For the ink pen look, ink min_frac specifies the minimum fraction of the original 
contour thickness (at contour segment orientations perpendicular to the stroke direction). The 
file_name specifies the name of the file that the contours are written to. 


It is also possible to get both the regular image (without contours) and one of the above at the 
same time. For example, to get the regular image and an image of the contours, write 


output "rgb" "myimage.rgb" 
output "contour,rgba" "contour_only" () 
output "rgb" "mycontourimage.rgb" 


2.8.4 Faster Contours 


If only simple outlines of objects are needed, contour_shader_simple can be used with contour- 
store_function_simple and contour_contrast_function_simple to get fast contour computations. 
Furthermore, very simple material shaders should be used (no illumination, shadow, reflection, 
refraction, or texture computations). 
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2.9 Multipass Rendering>: 


Multipass rendering is a new feature in mental ray 3.1.2 that allows rendering multiple scenes with 
the same frame number, resolution, oversampling parameters, and list of type of frame buffers, 
but different contents. This is useful if a scene is extremely complex, or consists of many distinct 
elements, so that rendering it all at once is impractical either because of the size, or because 
certain elements are expected to change and it would be too expensive to re-render the entire 
scene for each small change. Multipass rendering allows splitting such a scene into sub-scenes 
(called passes or layers), rendering each sub-scene, and putting the results together in a separate 
step called merging. 


Scenes are typically broken into sub-scenes by clustering geometry, for example one for each 
complex character or creature, or props such as vehicles, or backgrounds. Elements not present 
in a sub-scene are either omitted completely or replaced by very simple stand-ins that do not 
appear in the rendered pass image, for example simple invisible and nontraceable objects that 
cast shadows. This allows objects of one pass to cast shadows on objects in another pass. (In this 
particular case it is useful to enable the shadow BSP tree with the option statement bsp shadow 
on to manage the shadow stand-ins more efficiently.) 


Each pass render leaves a pass file in a directory specified by the user, using a pass statement list 
in the camera definition. Pass statements come in five forms: 


e pass write "filename" 
Save the current set of samples belonging to each rendered rectangle to the file filename. 


e pass merge read [...] write "fn" shader 
Merge the comma-separated list of pass file names in angle brackets, where a null file name 
("") stands for the current render results, and save the merged pass data. The options shader 
performs the merging. The default performs a depth and alpha blending merge. 


e pass prep read "fn" write "fn" shader 
Preprocess a pass file. The shader has random access to all samples. 


e pass delete "fn" 
Delete the file. 


e pass null 
Delete all pass statements in the camera. 


All pass prep statements are executed in order before rendering. During rendering, all pass and 
pass merge statements are executed in order, once for each finished rectangle. After rendering, all 
delete statements are executed. For more information on the syntax, see page 107. 


Merging is the operation of combining all samples for a pixel, sample by sample, to arrive at the 
final sample to be filtered into the pixel. Merging may simply choose the sample with the lowest 
depth, or also perform alpha blending or other operations based on the available frame buffers. 
Merging can either happen at the end of the last pass, or as a separate operation. mental ray will 
merge without rendering if there is no pass statement (of the first type above). If merging without 
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rendering, it is still necessary to provide some information about the scene that agrees with the 
settings in the pass sub-scenes: 


e an options block with a samples statement. 
e acamera with pass, output, and resolution statements. 


e acamera instance and root group containing the camera instance, and a render statement. 


The pass statement specifies the current pass number, the number of passes, and an optional 
directory to store the pass files (which can become large if there are many samples and many 
defined frame buffers, much larger than image files). Here is an example scene for merging only: 


link "passmerge.so" 
declare shader "mymerge" () version 1 end declare 
options "opt" 

samples ae | 


end options 


camera "cam" 


frame 1 

pass merge read [ "pass.0", "pass.1", "pass.2" ] "mymerge" () 
output "rgb" "out.rgb" 

resolution 150 128 


end camera 


instance "cam_inst" "cam" end instance 
instgroup "rootgrp" "cam_inst" end instgroup 
render "rootgrp" "cam_inst" "opt" 


Note that the camera specifies no pass write statement, so no rendering takes place and no 
geometry needs to be specified here. (If it were, it would be ignored.) The renderpass merge 
shader “mymerge” is responsible for putting the render passes together, sample by sample. Its 
implementation is described on page 305. The example there merges the scenes by Z depth, and 
since the merging is based on individual samples, any intersections will be properly anti-aliased 
(which they would not if the merging were based on images). If no merge shader is specified, 
mental ray will default to a simple depth sorting function with alpha blending. 


Note, however, that each pass is a separate scene with no knowledge about other scenes. This 
means that at points where objects in one pass intersect with objects in another pass in the 
final image, mental ray sees no reason to oversample the intersection because it does not exist 
at that time. Although mental ray will reconstruct low-sampling areas before merging, it may 
occasionally be necessary to use sampling parameters where the minimum number of samples 
is close to, or in extreme cases (where the objects are simple and nearly flat-shaded but highly 
detailed inter-pass intersections take place) even equal to the maximum number of samples. It 
is also recommended to turn jittering off because different passes may jitter sample position in 
different ways. 


2.10 Scene Example 181 


For the merge example above to work, it is necessary to first render the three pass files. This 1s 
done by adding pass statements to the camera: 


camera "cam" 
pass write "pass.0" 


end camera 


And similar for passes 1 and 2. These files are otherwise normal scene files. As mentioned before, 
the resolution and sampling parameters, and list of frame buffers (as defined by output and 
frame buffer statements) must agree. Pass files from hosts with different byte orders cannot be 
merged. No pass merge statements are required, unless merging should be done after rendering 
too. Note that if merging and rendering is done in one step, the pass being rendered is referenced 
in the pass merge statement with an empty string (""). This can be done in any pass — if rendering 
pass 2 of 3, for example, the pass merge statement would be 


pass merge read [ "pass.0", "", "pass.2" ] 
output "rgb" "rgb.out" 


Note that pass files are not intended for long-term archival. Although different versions of mental 
ray will generally accept the same pass merge files, major revisions may alter the file format. An 
informational warning will be printed if the version numbers do not agree, but this warning 
can be ignored. mental ray will detect incompatibilities and reject pass files that have the wrong 
version, resolution etc., or the wrong byte order. 


If renderpass mode is enabled, mental ray will automatically enable the depth (Z) frame buffer. 
This may change in future versions. 


2.10 Scene Example 
This example creates two images of a cube, each with a different camera and light: 


verbose on 
link "base.so" 
$include <base.mi> 


options "opt" 
samples as ae 
contrast oe. Made se ee Oe 
trace depth 2 2 

end options 


camera "cami" 
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frame 

output 

focal 

aperture 

aspect 

resolution 
end camera 


instance 


light "lighti" 


"mib_light_point" ( 
nod. 


Rea lor” 


1 


"rgb" "x. Feb" 


100 


144 .724029 


1.179245 
500 424 


"Shadow" on, 


"factor 
) 
origin 
end light 


instance "lightinsti" "lighti" 


material "mtl" opaque 

"mib_illum_phong" ( 
"ambience" 
"ambient" o 
"diffuse" af 
"specular" 1 1 
"exponent" 50, 
"lights 


) 


end material 


object “obji" 


" 1 


141.375732 83 


" [ "lightinsti" ] 


> ae 


visible shadow trace 


group 
=T 


end group 


"mesh" 


068787 


.179573 
068787 
179573 
1795/3 
.068787 
-L?9573 
. 068787 


OonorFr Oe 


"caminsti" "cami" 


Ne ND ®D N ®W 
NnODN WN 


end instance 


. 155799 
973234 
. 344949 
527515 
527514 
. 344948 
973235 
. 155800 


.116005 35.619434 


end instance 


.885710 
. 124060 
.619093 
457443 
. 142058 
. 580408 
475441 
soLa(9l 
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end object 
instance "insti" "obji" end instance 


instgroup "world" 
"caminsti" "lightinsti" "insti" 
end instgroup 


render "world" "caminsti" "opt" # render frame 1 


incremental camera "cami" 
frame 2 
output reo" "sy yen" 
aperture 100 

end camera 


incremental light "lighti" 
"mib_light_point" ( 
"color™ £0 1, 
) 
end light 


render "world" "caminsti" "opt" # render frame 2 


Chapter 3 


Using and Writing Shaders 


All color, displacement, contour, and other computation in mental ray is based on shaders. There 
are various types of shaders for different situations, such as material shaders to evaluate the 
material properties of a surface, light shaders to evaluate the light-emitting properties of a light 
source, lens shaders to specify camera properties other than the default pinhole camera, and so 
on. 


There are external shader libraries that support compatibility with Alias, Autodesk 3ds max, 
Dassault Systemes CATIA, SOFTIMAGE, SolidWorks, Wavefront, and others. Much of the 
power of mental ray relies on the possibility to write custom shaders and link them dynamically 
to mental ray at runtime. Custom shaders are written in C or C++, using the full language and 
library support available in these languages. 


Here are the steps necessary to create a new shader: 


e Write a .mi declaration for the shader, providing the shader name, return type, shader 
parameter names and types, and the version to mental ray. 


e Write a C shader parameter data structure that agrees exactly with the .mi parameter 
declaration. (The mkmishader utility can do this translation.) 


e Write the shader function in C or C++, using the correct signature. The shader computes 
a result from its shader parameters and the state, and by calling shader interface functions 
provided by mental ray. 


e Write a version shader (same name with _version appended to the name) that returns a 
version number that matches the version number in the .mi declaration. 


e If required, write initialization and exit shaders (same name as the shader with _init and 
-exit appended, respectively). 


e Compile and link the shader, and create a shared shader library (DSO or DLL). This step 
can be omitted but DSO/DLLs are easiest to use and much faster to link than objects or 
sources. Libraries must be installed on all machines on the net that are used as masters or 
network rendering slaves. 
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e Use a $include statement in the scene .mi file to load the .mi declaration and a link (or 
code or $code) statement to load the shader DSO/DLL (or source code). 


Note that if the shader is expected to work on Windows NT, all four function definitions (the 
shader, the version function, and the init and exit shaders) must be preceded with DLLEXPORT. 
This is a pseudo type specifier that makes the functions visible to users of the generated shader 
library. On Unix systems DLLEXPORT evaluates to an empty word. 


The shader is then ready to be used in the scene. These steps are described in detail below. 


3.1 Dynamic Linking of Shaders 


Shaders are written as C or C++ subroutines, stored in files with the extension “.c”. To use 
these shaders in a scene, they must be dynamically linked into mental ray at runtime. mental ray 
accepts shaders in three forms: 


e Directly as source code. The .mi file offers the code statement and the standalone renderer 
has a -code option. Both accept a source file with a .c extension. 


e In object format. Source files can be compiled to object code using Unix commands such as 
“cc -O -c source.c” (assuming that the shader source is in a file named source.c). The 
command may vary on some platforms, consult the manual (see “man cc)”. On Windows 
NT systems, shared libraries are called DLLs. This is the most common form on systems 
that do not support DSOs; it is faster than source because mental ray does not have to 
compile the shader. The compilation leaves a source.o file with the extension .0 (.obj 
on Windows) in the current directory. This file can be passed to mental ray using the link 
statement in the .mi file, or with the -Link option of the standalone renderer. 


e In DSO format. DSO stands for Dynamic Shared Object. DSOs are supported on all 
platforms except Windows NT, which use a simpler but similar system called DLL 
(Dynamic Link Library). DSOs have the extension .so on Unix/Linux systems and .d11 
on Windows NT systems. mental ray automatically substitutes .d11 for .so on Windows 
NT platforms and vice versa, so the same library filename can be used everywhere. 


To create a DSO, first compile the shader source to object format using cc as described above, 
then run the Unix command “ld -shared source.o”, again assuming that the object file is 
called source.o. This 1d command applies to Unix/Linux. Using DSOs is the fastest way to load 
shaders, there is very little overhead. DSOs, like object files, are loaded using link statements or 
-link options. 


The commands to create a DSO depend on the operating system type. To create a DSO named 
example.so from a source file example.c, use the following commands. Insert the -g command line 
option after -c to insert debugging information, or insert -O0 to compile an optimized version. 
On Linux, -g and -0 can be combined. Refer to the compiler documentation for details. 


3.1. Dynamic Linking of Shaders 187 


Linux x86, gcc 


Linux x86, icc 


Linux x86, 64 bits 


Linux IA 64 


Linux Alpha 


IRIX, 32 bits 
IRIX, 64 bits 


MacOS X 


HP/UX HPPA 


HP/UX IA 64 


IBM AIX 


Sun Solaris 


gcc -c -03 -fPIC -Bsymbolic! shader.c 
ld -export-dynamic -shared -o shader.so shader.o 


icc -c -02 -KPIC -Bsymbolic -tpp/ shader.c 
ld -export-dynamic -shared -o shader.so shader.o 
(Using the Intel compiler suite.) 


gcc -c -03 -fPIC -Bsymbolic -DBIT64 shader.c 
ld -export-dynamic -shared -o shader.so shader.o 


gcc -c -03 -KPIC -Bsymbolic -DBIT64 shader.c 
ld -export-dynamic -shared -o shader.so shader.o 


gcc -c -03 -ansi -fPIC -mieee -DBIT64 shader.c 
ld -export-dynamic -shared -o shader.so shader.o 


cc -n32 -03 -shared -o example.so example.c 
cc -64 -03 -DBIT64 -shared -o example.so example.c 


cc -c -03 -fPIC -dynamic -fno-common example.c 
libtool -flat_namespace -undefined suppress -dynamic 
-o example.so example.o 


cc -c -Aa +z example.c 
ld -b -o example.so example.o 


cc -c +03 +Onolimit +DD64 -Ae -Bprotected_def 
-Bdefault:keepsym.exp example.c 
cc +DD64 -b -o example.so example.o 


cc -c -03 example.c 
ld -o example.so example.o -bE:example.exp extra.so 
+bl:keepvexp —-bM:SRE. T5i2 -HSi2 -le 
example.exp is a user supplied export file for the shader and must contain 
the names of the exported symbols, one per line. keep.exp is the list of 
symbols exported by mental ray, either for use by shaders or for internal 
linking purposes. It is supplied with mental ray and can be referenced using 
an absolute path name. extra.so must be supplied to allow linking with 
shader libraries that are preloaded during runtime (such as physics. so) if 
functions from that library are used directly. 


cc -c -x03 -KPIC -D_REENTRANT example.c 
ld -lm -G -o example.so example.o -ldl 
(Using Sun CC. gcc can also be used, see Linux above.) 


'The -Bsymbolic option is supported by RedHat and SuSE Linux 8.0 and later. It makes it possible to use a different 
standard C++ library in the shaders than in mental ray, even though both are part of the same executable. This is important 
because mental ray uses a lowest-common-denominator library that is likely to differ from the default version used when 


compiling shaders. 


188 


Tru64 Unix 
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NT x86, icl 


NT x86, 64 bits 


NT JA 64 
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cc -c -newc -Q2 -ieee_with_no_inexact -DBIT64 -D_REENTRANT 
example.c 
ld -expect_unresolved ’*’ -shared -o example.so example.o 


cl /c /02 /G6 /MD /nologo /W3 -DWIN_NT example.c 

link /nologo /nodefaultlib:LIBC.LIB /OPT:NOREF 
/INCREMENTAL:NO /DLL /OUT:example.d1l 
example.obj shader.lib 

VC means Visual C++ 6 or up; earlier versions are too buggy. shader.1lib 

is a stub library that is provided with mental ray. It is necessary because 

Windows NT cannot automatically share symbols between modules sharing 

a process. 


icl /c /Ox /G7 /MD /nologo /W3 -DWIN_NT example.c 

xilink /nologo /nodefaultlib:LIBC.LIB /OPT:NOREF 
/INCREMENTAL:NO /DLL /OUT:example.d1l 
example.obj shader.1lib 

(Using the Intel compiler suite.) 


cl /c /GR /Zp8 /W3 /GX /GR /GF /02 /MD /nologo /W3 
-DWIN_NT -DBIT64 example.c 

link /nologo /nodefaultlib:LIBC.LIB /OPT:NOREF 
/INCREMENTAL:NO /DLL /OUT:example.d1l 
example.obj shader.lib 


ecl -c /GR /Zp8 /W3 /GX /GR /GF /02 /MD /nologo /W3 
-DWIN_NT -DBIT64 example.c 

xilink /nologo /nodefaultlib:LIBC.LIB /OPT:NOREF 
/INCREMENTAL:NO /DLL /OUT:example.d1l 
example.obj shader.1lib 


Compiling and creating DSOs requires that a C development environment is installed on the 
system. If the cc, 1d, etc. commands are not found, make sure that a development environment 
exists. On most platforms, it is a separate product that must be purchased separately. Dynamically 
loading a DSO does not require compilers or development options. 


If a host supports multiple programming models, such as IRIX with 32 and 64 bits, the options 
must agree with the version of mental ray. Use the Unix file command on mental ray and the 
shader library and make sure that they agree. If there is a mismatch, the run-time linker will print 


error messages like: 


/my/shader.so: 1234:ray: rld: Fatal Error: 
cannot successfully map soname ’/my/shader.so’ 
under any of the filenames /my/shader.so 
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The run-time linker always tries to match executables and libraries, which allows multiple ABIs 
to reside on the same system without conflicts. If the filename of the DSO given as an absolute 
pathname mental ray only tries to load that particular file. If it is given as a relative path, mental 
ray searches the DSO in a list of paths that can be supplied via the command line parameter 
(-1d_path) or the environment variable (MI_LLIBRARY_PATH). There is also a default search path 
(/usr/local/mi/1ib; .). A search list is a colon-separated (Unix) or semicolon-separated (Unix 
or Windows NT) list of paths to be searched. (Windows NT uses colons for drive letters.) 


Note that source code (.c extension) is normally portable, unless nonportable system features 
(such as fsqrt on SGIs) are used. This means that the shader will run on all other vendors’ systems 
unchanged. If the compilation fails and the shaders therefore are undefined, mental ray will — 
when calls of the undefined shaders are attempted — return miFALSE, which will generally leave 
the pixel sample black. 


Neither object files (. o extension) nor DSOs (.so extension) are portable. They must be compiled 
separately for each platform and, usually, for each major operating system release. For example, 
a Hewlett-Packard object file will not run on an SGI system, and an SGI IRIX 4.x object file 
cannot be used on an IRIX 6.x system, and vice versa. Also note that pointers are 32-bit values 
on some systems and 64-bit values on others, and that most but not all (IBM) processors require 
that 64-bit values such as doubles are stored at memory addresses evenly divisible by 8. 


On SGI systems, a shader can be debugged after it has been called for the first time, which attaches 
it to the program and makes its symbols available to the debugger. For this to work, the -g option 
must be given to the cc and 1d commands in all stages — compilation, linking, and shared-library 
building. Also, only DSO shaders are debuggable, not shaders loaded in object (.0) or source 


(.c) form. 


On non-SGI systems, debugging shaders is, unfortunately, difficult. The reason is that most 
debuggers cannot deal with parts of a program that have been dynamically linked. In general, the 
debugger will refuse to set breakpoints in dynamically linked shaders, and will step over calls to 
these shaders as if they were a single operating system call. Some vendors are working on fixing 
these problems, but at this time the only option on non-SGI systems is using mi_info or mi_debug 
statements in the shader sources. Avoid printf because it is lost on slave hosts and because it can 
cause problems at runtime. 


Windows NT shader libraries must use at least one shader interface call (any true C function 
beginning with mzi_), or an error message “DLL_SetModuleHandle not found” will occur. 


When a shared library is loaded that contains a function module_init, that function is called just 
after the library was loaded, before the first shader in it is called. Conversely, if it contains a 
function module_exit, that function is called just before the library is unloaded, after the last call 
to a shader in this library. Note that in the case of irrecoverable errors at any time after the library 
was loaded module_exit is not guaranteed to be called. Neither module init nor module_exit may 
rely on any shader interface services that assume that a rendering operation is in progress. Message 
functions such as mi_info are available. Note that this feature is not supported on IBM systems 
and should not be used for portable shaders. 
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Note that if aC++ compiler is used to compile a shader, all names (shader, init, exit, version) need 
to be declared with extern "C". This is necessary because C++ compilers “mangle” symbols by 
tacking on type information, so mental ray cannot find the shader in the library. This will result 
in a “declaring nonexisting function” warning, and the shader will not be called. 


3.2 Coordinate Systems 


Internal space is the coordinate system mental ray uses to present intersection points and other 
points and vectors to shaders. All points and vectors in the state except bump basis vectors (which 
are in object space) are presented in internal space, namely, org, dir, point, normal, normal- 
geom, motion and derivs. The actual meaning of internal space is left undefined, it varies between 
different versions of mental ray and depends on the space statement in the options block in the 
.mi file. A shader must not assume that internal space is identical to world space, even though 
this is true in most scenes. 


World space is the coordinate system in which modeling and animation takes place. 


Object space is a coordinate system relative to the object’s origin. The modeler that created the 
scene defines the object’s origin. Most translators use the center of the bounding box of the object 
as the object origin. 


Camera space is a coordinate system in which the camera is at the coordinate origin (0,0,0) with 
an up vector of (0, 1,0) and looking down the negative Z axis. 


In addition to these 3D coordinate spaces, raster space is a two-dimensional pixel location on the 
screen bounded by (0, 0) in the lower left corner of the image, and the rendered image resolution. 
The center of the pixel in the lower left corner of raster space has the coordinates (0.5, 0.5). 


Screen space is defined such that (—1, —1/a) is in the lower left corner of the screen and (1, 1/a) 
is in the upper right, where a is the aspect ratio of the screen (the relation between its width and 


height). 


Most shaders never need to transform between spaces. Texture shaders frequently need to operate 
in object space; for example, in order to apply bump basis vectors to state—normal, the normal 
must be transformed to object space before the bump basis vectors are applied, and back to 
internal space before the result is passed to any mental ray function such as mi_trace_reflection. 
mental ray offers 18 functions to convert points, vectors and normals between coordinate spaces: 
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Junction 


mi_point_to_world(s,p,,p) internal point to world space 
mi_point_to_camera(s,p,,p) internal point to camera space 
mi_point_to_object(s,p,,p) internal point to object space 
mi_point_from_world(s,p,,p) world point to internal space 
mi_point_from_camera(s,p,,p) camera point to internal space 
mi_point_from_object(s,p,,~) object point to internal space 
mi_vector_to_world(s,v,,v) internal vector to world space 
mi_vector_to_camera(s,v,,V) internal vector to camera space 
mi_vector_to_object(s,v,,v) internal vector to object space 
mi_vector_trom_world(s,v,,v) world vector to internal space 
mi-_vector_from_camera(s,v,,v) | camera vector to internal space 
mi_vector_from_object(s,v,,v) | object vector to internal space 
mi_normal_to_world(s,v,,v) internal normal to world space 
mi_normal_to_camera(s,v,,V) internal normal to camera space 
mi_normal_to_object(s,v,,v) internal normal to object space 
mi_normal_from_world(s,v,,v) | world normal to internal space 
mi_normal_from_camera(s,v,,v) | camera normal to internal space 
mi_normal_from_object(s,v,,v) | object normal to internal space 


Point and vector transformations are similar, except that the vector versions ignore the translation 
part of the matrix. Normal transformations are similar to vector transformations, except that the 
transpose of the inverse transformation matrix is used. In this way it is ensured that if a vector and 
a normal are orthogonal in one coordinate system they remain orthogonal after they have been 
transformed to a different coordinate system. This holds for arbitrary, not necessarily orthogonal 
transformations. 


The length of vectors is preserved only if the transformation matrix does not scale. The mi_point- 
transform and mi_vector_transform functions are also available to transform points and vectors 
between arbitrary coordinate systems given by a transformation matrix. mi_vector_transform_T 
transforms with the transpose of the matrix and can be used for the transformation of normals. 


3.3 Shader Type Overview 
There are many types of shaders, all of which can be substituted by user-written shaders: 


e material shaders describe the visible material of an object. They are the only mandatory 
part of any material description. Material shaders are called whenever a visible ray (eye 
ray, reflected ray, refracted ray, or transparency ray) hits an object. Material shaders have a 
central function in mental ray. 


e volume shaders are called to account for atmospheric effects encountered by a ray. The state 
(see below) distinguishes two types of volume shaders: the standard volume shader that is 
called in most cases, and the refraction volume shader that is taken from the object material 
at the current intersection point, and becomes the standard volume shader if a refraction or 
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transparency ray is cast. Many material shaders substitute a new standard volume shader 
based on inside/outside calculations. Volume shaders, unlike other shaders, accept an input 
color (such as the one calculated by the material shader at the last intersection point) that 
they are expected to modity. 


light shaders implement the characteristics of a light source. For example, a spot light 
shader would use the illumination direction to attenuate the amount of light emitted. A 
light shader is called whenever a material shader uses a built-in function to evaluate a light. 
Light shaders normally cast shadow rays if shadows are enabled to detect obscuring objects 
between the light source and the illuminated point. 


shadow shaders are called instead of material shaders when a shadow ray intersects with an 
object. Shadow rays are cast by light sources to determine visibility of an illuminated object. 
Shadow shaders are basically light-weight material shaders that calculate the transmitted 
color of an object without casting secondary or shadow rays. Frequently, material shaders 
are written such that they can also be used as shadow shaders. 


environment shaders are called instead of a material shader when a visible ray leaves 
the scene entirely without intersecting an object. Typical environment shaders evaluate a 
texture mapped on a virtual infinite sphere enclosing the scene (virtual because it is not part 
of the scene geometry). 


photon shaders are used to propagate photons through the model in order to simulate 
caustics and global illumination. Photon shaders are used in a preprocessing step in which 
photons are emitted from the light sources into the model (just as a real light source emits 
photons into the world). Each photon is traced through the scene using a technique called 
photon tracing which is similar to ray tracing. As with ray tracing a photon is reflected of 
a specular mirror surface in the mirror direction. The most important difference is the fact 
that the photon shader modifies the photon energy before reflecting the photon unlike ray 
tracing which traces a ray and then modifies the result accordingly (for example multiplies 
it with the specular reflection coefficients). Photon shaders also store information about the 
incoming photon in a global photon map which contains all photons stored in the model. 
This photon map is then used by the material shaders during the rendering step (ray tracing 
step) to simulate caustics and global illumination. Frequently, material shaders are written 
such that they can also be used as photon shaders (and also shadow shaders). 


photon volume shaders are similar to photon shaders in the same way that volume shaders 
are similar to material shaders: they compute indirect light interactions in volumes, such as 
volume scattering. 


photon emitter shaders are used to control the emission of photons from a light source. 
Combined with the light shaders it is possible to simulate complex light sources with 
complex emission characteristics. Photon emitters are only used if caustics or global 
illumination are enabled, to construct a photon map before the actual rendering takes 
place. 


texture shaders come in three flavors: color, scalar, and vector. Each calculates and returns 
the respective type. Typical texture shaders return a color from a texture image after some 
appropriate coordinate transformation, or compute a color at a location in 3D space using 
some sort of noise function. Their main purpose is to relieve other shaders, such as material 
or environment shaders, from performing color and other computations. For example, if 
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a marble surface were needed, it should be written as a texture shader and not a material 
shader because a texture shader does not have to calculate illumination by light sources, 
reflections, and so on. It is much easier to write a texture shader than a material shader. 
mental ray never calls a texture shader directly, it is always called from one of the other 


types of shaders. 


e displacement shaders are called during tessellation of polygonal or free-form surface 
geometry, a procedure that creates triangles to be rendered. Displacement shaders are 
called to shift the created vertices along their normals by a scalar distance returned by the 
shader. mental ray supports approximation controls that allow adjusting the tessellation to 
better resolve curvature introduced by displacement shaders. 


e geometry shaders are run before rendering begins. They create geometry procedurally by 
using a function call library that closely follows the .mi2 scene description language. Unlike 
displacement shaders, which are called once per vertex, geometry shaders are responsible 
for creating an entire object or object hierarchy (each of which, when tessellated later, can 
cause displacement shader calls). 


e contour shaders come in four different flavors: contour store shaders, contour contrast 
shaders, contour shaders, and contour output shaders. For details see section 2.8. 


e lens shaders are called when a primary ray is cast by the camera. They may modify the eye 
ray’s origin and direction to implement cameras other than the standard pinhole camera, 
and may modify the result of the primary ray to implement effects such as lens flares. 


e output shaders are different from all other shaders and receive different parameters. They 
are called when the entire scene has been completely rendered and the output image resides 
in memory. Output shaders operate on the output image to implement special filtering or 
compositing operations. Output shaders are not associated with any particular ray because 
they are called after the last ray is completed. 


e lightmap shaders can be attached to materials to scan the surface of an object, collecting data 
and optionally writing a writable texture to disk. This can be used to “bake” illumination 
solutions into a texture, for example. 


e state shaders can be attached to the options block. They are called on four occasions: Once 
a state is created, once a state is destroyed, just before the first regular shader for a sample 
is called, and just before the computed sample is written to the frame buffer. These four 
cases may be distinguished by different constants passed to the shader. These shaders may 
be used to manipulate the state of mental ray. A common application is to add some data 
to the state that is needed by various shaders during rendering. 


The following diagram illustrates the path of a ray cast by the camera. It first intersects with a 
sphere at point A. The sphere’s material shader first casts a reflection ray that hits a box, then a 
refraction ray that intersects the sphere at its other side T, and finally it casts a transparency ray 
that also intersects the sphere, at D. (This example is contrived, it is very unusual for a material 
shader to cast both a refraction and a transparency ray.) The same material shader is called at points 
A, T, and D. In this example, the reflection trace depth may have prevented further reflection 
rays to be cast at T and D. 
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E1 


. ae 9. environment shader of sphere(2) object is called 
5. environment shader of sphere(2) object is called FSI (4) 00) 


refracted ray 


6. refraction volume shader of sphere(2) object is called transparency ray 


4. material shader of sphere object is called 10. refraction volume shader of sphere(2) object is called 


8. material shader of sphere object is called 


11. refraction volume shader of sphere(1) object is called 


3. volume shader of box material is called 


2. material shader of box object is called 


7. refraction volume shader of sphere(1) object is cal 


reflected ray 


Sphere object 


1, material shader of sphere object is called Box Object 


12. view volume shader is called 


First-generation eye ray 


13. end result is stored in frame buffer 


Camera 


The annotations set in ztalics are numbered; the events described happen in the sequence given 
by the numbers. 


Since material shaders may do inside/outside calculations based on the surface normal or the 
parent state chain (see below), the volume shaders are marked (1) and (2), depending on whether 
the volume shader left by A or by T/D in the refraction volume field of the state. The default 
refraction volume shader is the one found in the material definition, or the standard volume 
shader if the material defines no volume shader. For details on choosing volume shaders, see the 
section on writing material and volume shaders. Note that the volume shaders in this diagram 
are called immediately after the material shader returns. 


mental ray 3.0 also supports a autovolume mode, enabled in the options block with autovolume 
on. In this mode, mental ray finds out which volumes the camera is in by casting a single ray 
to infinity, and offers four shader API functions that tell the shader which volumes the current 
intersection point is in. Shader declarations may contain autovolume levels that define which 
volumes mix and which volumes displace others. 
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The next two diagrams depict the situation when the material shader at the intersection point 
M requests a light ray from the light source at L, by calling a function such as mi_sample_light. 
This results in the light shader of L to be called. No intersection testing is done at this point. 
Intersection testing takes place when shadows are enabled and the light shader casts shadow rays 
by calling mi_trace_shadow. This function is called only once but may result in more than one 
shadow shader call. There are four different modes for shadow casting, listed in the order of 
increased computational cost: 


e shadow off 
No shadows are computed, and no shadow shaders are called. Call to mi_trace_shadow 
return immediately without modifying the result color. 


e shadow on 
For each obscuring object (A and B), a shadow ray is generated with the origin L and the 
intersection point A or B, and the shadow shaders of objects A and B are called to modity 
the light emitted by the light source based on the transparency attributes of the obscuring 
object. No shadow ray is generated for the segment from B to M because no other obscuring 
object whose shadow shader could be called exists. Although shadow rays always go from 
the light source towards the illuminated point in this mode, the order in which the shadow 
shaders are called is undefined. If an object without shadow shader is found, or if a shadow 
shader returns miFALSE, it is assumed that no light reaches the illuminated point and the 
search for more obscuring objects is stopped (although the light shader has the option of 
ignoring this result and supplying some light anyway). See the first diagram below. The 
volume shader of the illuminated object M is applied to the entire distance between M and 


Ls. 


e shadow sort 
Same as the previous method, but shadow shaders are called in distance order, object closest 
to the light source first. In the first diagram, steps 4 and 5 may be reversed. 


e shadow segments 

This mode is more sophisticated than the others. Shadow rays become similar to visible rays; 
they travel in segments from the illuminated point to the first obscuring object, then from 
there to the next obscuring object, and so on until the light source is reached. This means 
that shadow rays travel in the opposite direction, and one shadow ray’s end point becomes 
the next shadow ray’s origin. Volume shaders are called for each of these segments, and 
every shadow shader must perform inside/outside calculations to store the correct volume 
shader in state — volume much like material shaders to. This mode is preferred if volume 
effects should cast shadows. 


Note that the shadow segment mode requires complex shadow shaders to behave differently. 
Every shadow shader must be able to work with all these modes, so shadow shaders that deal 
with volumes or depend on the ray direction must test state —> options — shadow to determine 
the mode. In case an incorrectly implemented shadow shader fails to call mi_trace_shadow-seg to 
evaluate other shadows, mental ray will call m_trace_shadow_seg and then call the shadow shader 
again, thus simulating the effect. 


The first diagram shows the ray casting order and the ray directions for the shadow on and 
shadow sort modes: 
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3. light shader traces the shadow 


- Light Source 
r 

Camera 6. volume shader from the material at M is L 

\ called for the entire distance from L to M 

O 

Shadow ray 
Eye ray (or any other visible ray) 
A 
4. shadow shader of object A is called. Obscuring Object A 

Shadow ray 


5. shadow shader of object B is called 


7. view volume shader is called 


Obscuring Object B 


Light ray 


1. material shader is called 
2. material shader traces the light 


llluminated Object 


The next diagram shows the same situation in shadow segments mode: 


3.3. Shader Type Overview 


3. light shader traces the shadow 


hak é Light Source 
Camera L, 
\ 


O 


8. refraction volume shader of A is called... 


Shadow ray 


Eye ray (or any other visible ray) 


6. shadow shader of object A is called’ 
7. Shadow shader traces next shadow segment 


Obscuring Object A 


9. refraction volume shader of B is called..__ 


Shadow ray 


4. shadow shader of object B is called. 


5. shadow shader traces next shadow segment. 
11. view volume shader is called S 


Obscuring Object B 


Light ray Shadow ray 
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10. volume shader of material at M is called 


_ 1. material shader is called 
~ « 2, material shader traces the light 


Illuminated Object 


The following diagram illustrates the path of a photon shot from the light source in the caustics 
or global illumination preprocessing phase. First a photon is traced from the light source. It hits 
object A, and the photon material shader of object A is called. The photon material shader stores 
energy at the intersection point and determines how much energy is reflected and how much is 
refracted, and the directions of reflection and transmission. It then traces a new photon from A, 
in the reflection direction, or in the transmission direction, or both. The reflected photon hits 
object B, and the photon material shader of object B is called. The photon material shader of 


object B stores energy at the intersection point and shoots a new photon. 
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Light Source 
Object B C) 


Reflected photon 
2. photon material shader of object B is calle 


Photon 


1. photon material shader of object A is called 


Object A 


Refracted photon 


The remainder of this chapter describes how to write all types of shaders. First, the concepts of 
ray tracing state parameter passing common to all shaders are presented, followed by a detailed 
discussion of each type of shader. 


3.4 State Variables 


Every shader needs to access information about the current state of mental ray, and information 
about the intersection that led to the shader call. This information is stored in a single structure 
known as the state. Not all information in the state is of interest or defined for all shaders; for 
example, lens shaders are called before an intersection is done and hence have no information 
such as the intersection point or the normal there. See page 224 for a table of which variable is 


available in which type of shader. 


It is recommended to call the state parameter that shaders receive as a formal parameter state 
because some macros provided in the shader -h include file that require access to the state rely on 
this name (namely, the typed mz_eval_* variants). The state, and everything else needed to write 
shaders, is defined in shader .h, which must be included by all shader source files. 


Before a shader is called, mental ray prepares a new state structure that provides global information 
to the shader. This state may be the same data structure that was used in the previous call (this is 
the case for shaders that modify another shader’s result, like lens, shadow, and volume shaders); or 
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it may be a new state structure that is a copy of the calling shader’s state with some state variables 
changed (this is done if a secondary ray is cast with one of the tracing functions provided by 
mental ray). For example, if a material shader that is using state A casts a reflected ray, which hits 
another object and causes that object’s material shader to be called with state B, state B will be a 
copy of state A except for the ray and intersection information, which will be different in states 
A and B. State A is said to be the parent of state B. The state contains a parent pointer that allows 
sub-shader to access the state of parent shaders. If a volume shader is called after the material 
shader, the volume shader modifies the color calculated by the material shader, and gets the same 
state as the material shader, instead of a fresh copy. 


The state also contains a child pointer that, together with the parent pointer, forms a double- 
linked list of states. After a shader casts a ray, the state used by the ray remains available after 
the trace call returns. This means that if trace call returns true, the shader has full access to the 
intersection information, label value, and all other state variables used by the child shader. For 
example, the shader for a completely transparent object may decide to copy state — child — label 
to state — label atter mi_trace_transparency returns. Only the most recent discarded child state 
is retained; state — child — child is undefined. 


This means that it is possible to pass information from one shader to another in the call tree for 
a primary ray, by one of two methods: either the parent (the caller) changes its own state that 
will be inherited by the child, or the child follows the parent pointer. The state contains a user 
pointer that a parent can store the address of a local data structure in, for passing it to sub-shaders. 
Since every sub-shader inherits this pointer, it may access information provided by its parent. A 
typical application of this are inside/outside calculations performed by material shaders to find 
out whether the ray is inside a closed object to base the interpretation of parameters such as the 
index of refraction on. 


Note that the state can be used to pass information from one shader to sub-shaders that are lower 
in the call tree. Care must be taken not to destroy information in the state because some shaders 
(shadow, volume, and the first eye shader) re-use the state from the previous call. In particular, 
the state cannot be used to pass information from one primary (camera) ray to the next. Static 
variables can be used in the shader for this purpose, but care must be taken to avoid multiple 
access on multiprocessor shared-memory machines. On such a machine, all processors share the 
same set of static variables, and every change by one processor becomes immediately visible to 
all other processors, which may be executing the same shader at the same time. Locking facilities 
are available in mental ray to protect critical sections that may execute only once at any time. 


Here is acomplete list of state variables usable by shaders. Variables not listed here are for internal 
use only and should not be accessed or modified by shaders. Some variables are available only in 
some types of shaders; see the “State Variables by Shader Type” section on page 224. The first 
table lists all state variables that remain unchanged for the duration of the frame: 
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3.4.1 Frame 


int version shader interface version 
miTag camera_inst tag of camera instance 
miCamera * camera camera information 
miOptions * options general rendering options 


version The version number of the interface and the state structure. Useful to 
check if the version is compatible with the shader. Version 1 stands for 
mental ray 1.8, version 2 stands for 1.9 and 2.0. 


camera_inst The camera instance is a data structure in the mental ray database that 
contains transformation information about the camera. Like all other 
tags in the state, a pointer to that data structure can be obtained by 
calling mi_db_access with the tag as the only argument. This function 
returns a void pointer to the accessed data structure. After the pointer 
is no longer used, the pointer must be “returned” by calling mi_db- 
unpin with it. Failure to do so will abort rendering. 


The camera data structure pointed to by camera has the following fields. None of these may be 
written to by a shader. 


miBoolean orthographic orthographic rendering 
float focal focal length of the camera 
float aperture aperture of the camera 

float aspect aspect ratio ~ 

miRange clip Z clipping distances 

int x_resolution image width in pixels 

int y-resolution image height in pixels 

int window.xl left image margin 

int window.yl bottom image margin 

int window. xh right image margin 

int window. yh top image margin 

miTag volume camera volume (atmosphere) 
miTag environment camera environment shader 
miTag lens lens shader or lens shader list 
miTag output output shader or output shader list 
int frame frame number 

float frame_time frame time in seconds 

float frame_field 0: frame, 1: even field, 2: odd field 
float x_offset x offset of image in pixels 
float y-offset y offset of image in pixels 
miTag userdata’* user data scene element, or 0 


3.4 State Variables 


orthographic 


focal 


aperture 


aspect 


clip 


x_resolution 
y-resolution 


window 


volume 


environment 


lens 


output 
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This flag is miTRUE if the renderer is in orthographic mode, and 
miFALSE if it is in perspective mode. 


The focal length of the camera (the distance from the origin in camera 
space to the viewing plane that the image pixels are mapped on). 


The aperture of the camera (the width of the viewing plane in camera 
space). 


The aspect ratio (the ratio of the width and height of the viewing plane 
in camera space). 


This data structure has two members, min and max, that specify the 
hither and yon clipping planes in camera space for scanline rendering. 
Objects will be clipped if their Z coordinate in camera space is less 
than -max or greater than -min. 


The x resolution of the image in pixels. 
The y resolution of the image in pixels. 


The window specifies the lower left and the upper right pixel of the 
sub-region of the image to be rendered. If x/ and y/ are 0 and xh and yh 
match or exceed the resolution minus one, the entire image is rendered. 
The window is clipped to the resolution. Pixels outside the window 
are set to black. 


The global volume (atmosphere) shader from the camera that is used 
for attenuating rays outside of objects, such as the primary ray from 
the camera to the first object intersection. Material shaders inherit this 
volume shader because the volume state variable defaults to the camera 
volume, but shaders may override the volume. See below. 


The environment (reflection map) shader of the camera. It is used to 
assign a color to primary eye rays that leave the scene without ever 
intersecting an object. Material shaders that do not define their own 
environment shaders for evaluation of local reflection maps inherit the 
camera environment shader. Reflection maps give the illusion of true 
raytraced reflections by looking up a texture based on the reflection 
direction. 


The list of lenses applied to the standard pinhole camera. Each lens 
shader in this list is called when a primary ray leaves the camera. 


The list of output shaders and file outputs attached to the camera. 
File outputs are encoded in special miFunction data structures that 
contain a file name and various miscellaneous data instead of a shader 
reference. 
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pass? The list of multipass rendering statements. 


frame The current frame number. In field mode, this is the field number, two 
successive frames rendered by mental ray are combined into a single 
output frame by an output shader. In field mode, the odd frame is the 
first frame and the even frame is the second. 


frame_time The current frame number, expressed as a time in seconds. The relation 
between frame and frame_time depends on the frame rate. Both 
numbers are taken verbatim from the input scene, mental ray does 
not change or verify either number. If the frame time is omitted in the 
.mi file, it is set to 0.0. 


x_offset The X offset of the rendered image. The default value is 0.0 which 


means that the image will be centered on the camera’s axis. 


y-offset The Y offset of the rendered image. The default value is 0.0 which 
means that the image will be centered on the camera’s axis. 


userdata User data blocks are independent named toplevel scene entities that 
hold structured or unstructured data of any kind. Structured data is 
declared much like shader parameters, while unstructured data is a raw 
byte stream with a fixed size. User data is useful for large amounts of 
shared scene data. 


The options field in the state contains all rendering options specified in the scene, and possibly 
overridden by the command line. Since the number of options is very large, and since they are 
rarely used in a shader, the description can be found at the end of this section, on page 213. 


3.4.2 Image Samples 


The state variables in the next table describe an eye (primary) ray. There is one eye ray for every 
sample that contributes to a pixel in the output image. If a material shader that evaluates a material 
hit by a primary ray casts secondary reflection, refraction, transparency, light, or shadow rays, 
all shaders called as a consequence will inherit these variables unmodified: 


miScalar raster_x X coordinate of image pixel 
miScalar raster_y Y coordinate of image pixel 


miFunction * shader current shader 
miLock global_lock lock shared by all shaders 
short thread current thread 


raster_x The X coordinate of the point in raster space to be rendered. Raster 
space is the pixel grid of the rendered image file, with 0/0 at the lower 
left corner. 
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raster_y The Y coordinate of the point in raster space to be rendered. In output 
shaders executing in parallel mode because state — dist is nonzero, it 
contains the number of the first scanline of the scanline block to write. 


shader This pointer points to a data structure describing the current shader. 
The fields usable by shaders are lock, which is a lock shared by all 
calls to this shader, miTag next_function for chained shaders such 
as lens shaders, and char parameters[] which contains the shader 
parameters. The latter is redundant for the current shader because the 
parameter pointer is also passed as the third shader argument, but it 
can be used to find the parameters of parent shaders. This should be 
used with care because the C data structure of parent shader parameter 
lists is not generally known. 


Note that mental ray 3.x no longer supports state — shader — user.p. 
It is necessary to use mi_query with miQ_FUNC_USERPTR to retrieve the 
user pointer. This method works in mental ray 2.1 as well. 


global_lock This lock is shared by all shaders, regardless of their name. It can be 
used to lock critical sections common to all shaders. For example, it 
could be used to protect a nonreentrant user-defined random-number 
generator, or initialization of a more specific set of locks. It is pre- 
initialized by mental ray; do not initialize or delete it. 


thread The current thread number. This is a faster way of finding the thread 
number than calling mi_par_localvpu?'. Note that mental ray 3.0 may 
create and destroy threads at any time, and may create threads with 
higher numbers than specified on the command line with -threads. 
The thread number should not be used to index static arrays in 
mental ray 3.x because there is no way to compute the necessary size 
of this array when allocating it! 
a This field is valid only in light shaders. It specifies the number of 
times the light shader has already been called in order to oversample 
an area light source. It is 0 for the first call. The shader may change this 
value just before returning (miBoolean) 2, which aborts the sample 
loop and changes the value that the material shader will divide by to 
compute the average. In particular, a light shader for a user area light 
might set the count to 1 so that the material shader considers each 
sample as a separate light. This is useful for natural light “chrome 
dome” illumination. In mental ray 3.2, the count field is also valid in 
multipass rendering in renderpass merge shaders, where it contains 
the number of passes to merge. 


coun 


The absence of state — shader — user.p and a fixed upper limit on the number of threads are the 
two major differences between mental ray 2.x and 3.x that impact shader development. 
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3.4.3 Rays 


Whenever a ray is cast the following state variables are set to describe the ray: 


miState * parent state of parent shader 
miState * child state of child shader 
miRay_type type type of ray: reflect, light... 


miCBoolean 


void * 
miVector 


miVector 
float 


miTag 
miTag 
int 
int 
int 


parent 


child 


type 


scanline 
cache 


org 
dir 
time 


volume 
environment 
reflection_level 
refraction_level 


face 


from scanline algorithm 
RC intersection cache 

start point of the ray 
direction of the ray 

shutter interval time 
volume shader of primitive 
environment shader 
current reflection ray depth 
current refraction ray depth 


facing flag for sub-rays 


Points to the state of the parent ray. In the first lens shader, it is NULL. 
In subsequent lens shaders, it points to the previous lens shader. In 
the material shader that is called when the primary ray hits an object, 
it points to the last lens shader’s state, or is NULL if no lens shader has 
been applied. For material shaders called when a secondary reflection 
or refraction ray hits an object, it points to the parent material shader 
that cast the ray. In light shaders and environment shaders, it points 
to the state of the shader which requested the light or environment 
lookup. For shadow shaders, it points to the state of the light shader 
that started the shadow trace. In volume shaders, its value is the same 
as for a material or light shader of the same ray. 


Points to the state of the most recent child ray. After a function that 
created a separate state returns, this state is still accessible to the caller 
of the function through this pointer. For example, mi_trace_refraction 
constructs a state when hitting geometry before calling the material 
shader attached to that geometry with this state. After it returns, the 
new state can be accessed by the caller of m1_trace_refraction to access 
state — user, state — label, and all other local information. 


Specifies the reason for this ray. This is an enumerator. Some values 
became available in mental ray 3.0 to allow shaders to differentiate, 
but the underlying features were already present in mental ray 2.1. 
This may require shader changes to add case statements to existing 
switch blocks. 


miRAY_EYE primary rays from the camera. 
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miRAY_TRANSPARENT 
miRAY_REFRACT 
miRAY REFLECT 
miRAY_SHADOW 


miRAY_LIGHT 


miRAY_ENVIRONMENT 


miRAY_DISPLACE 
miRAY_OUTPUT?~* 


miRAY_FINALGATHER>~ 


miRAY_LM_VERTEX?” 


miRAY_LM_MESH>* 


miRAY_PROBE?'! 


miRAY_NONE 


miPHOTON_LIGHT 
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transparency rays cast by a material shader. 
refraction rays cast by a material shader. 
reflection rays cast by a material shader. 
light rays cast from a light source. 

rays cast by a material shader when a light 
source is evaluated (which may result in 


the light source casting shadow rays back). 


rays that sample an environment (reflec- 
tion) map. 


is set for displacement shaders. 
is set for output shaders. 


is set for finalgather rays originating at the 
final gather point. 


is set for lightmap shader in vertex scan 
mode. 


is set for lightmap shader in mesh output 
mode. 


is used by rays cast by mi_trace_probe in 
mental ray 3.1 or later. Earlier versions used 
miRAY_NONE. 


is a catch-all for other types of rays. 


is a photon emitted from a light source. 


miPHOTON_REFLECT_SPECULAR 


is a photon reflected specularly from a 
surtace. 


miPHOTON_REFLECT_GLOSSY 


is a photon reflected glossily from a sur- 
face. 


miPHOTON_REFLECT_DIFFUSE 


is a photon reflected diffusely from a 
surface. 
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scanline 
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miPHOTON_TRANSMIT_SPECULAR 
is a photon transmitted specularly through 
a surface. 


miPHOTON_TRANSMIT_GLOSSY 
is a photon transmitted glossily through a 
surface. 


miPHOTON_TRANSMIT_DIFFUSE 
is a photon transmitted diffusely through 
a surface. 


miPHOTON_TRANSPARENT is a photon transmitted directly (ie., with- 
out refraction) through a surface. 


miPHOTON_ABSORB°* is a photon being absorbed. 


miPHOTON_SCATTER_VOLUME?* 
is a photon scattered in a volume. 


miPHOTON_EMIT_CAUSTIC?* 
is a caustics photon to be cast by a photon 
emitter shader attached to a light source. 


miPHOTON_EMIT_GLOBILLUM>* 
is a global illumination photon to be cast 
by a photon emitter shader attached to a 
light source. 


The ray type (state — type) can be queried with the following macros: 


miRAY_PRIMARY (raytype) 
is true if the raytype is a primary or a 
transparency ray. 


miRAY_SECONDARY (raytype) 
is true if the raytype corresponds to a ray 
generated at an intersection point. 


miRAY_PHOTON(raytype) is true if the raytype is one of the 
miPHOTON_* rays. This macro can be used 
to separate the photon tracing part of a 
shader from the regular ray tracing part. 


This flag is set if the current intersection was found by means of the 
scanline rendering algorithm. 


3.4 State Variables 


cache 


Org 


dir 


time 


volume 


environment 


reflection_level 
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This variable is used by the renderer internally to improve speed. Its 
existence determines which shaders may call which tracing functions. 
By setting this pointer to 0, the shader can ease these restrictions and 
call tracing functions that are not normally legal for this type of shader. 
For details, see the section Shaders and Trace Functions below. 


The origin (start point) of the ray in internal space. In the primary 
material shader, it is set by the last lens shader, or is (0, 0, 0) if there is 
no lens shader and the default non-orthogonal pinhole camera is used. 
In all other material shaders, it is the previous intersection point. In 
light and shadow shaders, it is the origin of the light source. If the light 


source does not have an origin, it is undefined. 


The direction of the ray in internal space. This is basically the 
normalized difference between point and org, pointing towards 
the current intersection point (except in the case of directional light 
sources that have no origin; in this case the light direction is used). 
Light and non-segmented shadow rays point from the light source to 
the intersection. 


The time of the ray in the shutter interval. If motion blurring is turned 
off by setting the shutter time to 0.0 (or to the shutter delay?! value), 
the time is fixed at the shutter value. Otherwise, it is systematically 
sampled in the range from the shutter delay*' to the shutter time. 


The volume shader to be applied to the ray. The volume shader is 
called immediately after the material shader returns, without any 
change to the state. The volume shader changes the result color 
of the material shader to take the distance the ray to the material 
has traveled into account. For primary rays this is the volume of 
the camera, for reflection and light rays the volume of the parent, 
and for refraction and transparency rays the refraction_volume 
of the parent. Note that the mi_trace_refraction and mi_trace_ 
transparent functions copy refraction_volume to volume to 
ensure that sub-shaders use the volume shader that applies to the 
interior of the object. Volume shaders are also applied to light rays. 
This state variable is ignored in autovolume’* mode. 


The active environment shader. For primary rays this is the environ- 
ment of the camera. For reflection and refraction rays the active shader 
is taken from the material, if it specifies an environment shader. If it 
does not, the environment shader defaults to the environment shader 
in the camera, if present. The purpose of the environment shader is to 
provide a color if a ray leaves the scene entirely. 


The reflection level of the ray. It may range from 0 for primary rays 
to reflection_depth minus one. The trace_depth imposes another 
limit: The sum of reflection_level and refraction_level must 
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refraction_level 


face 


3.4.4 Intersection 
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be one less than trace_depth. A shader may decrement or reset the 
reflection level to circumvent the restrictions imposed by the trace 
depth state variables. The level fields are also used during photon 
tracing, and measure the photon trace depths in this case. 


The refraction level of the ray. This is equivalent to the reflection level 
but applies to refraction and transparency (which is a variation of 
refraction that does not take the index of refraction into account) rays. 
A shader may decrement or reset the refraction level to circumvent 
the restrictions imposed by the trace depth state variables. 


This field is initialized with state — options — face, but can be 
changed by shaders before casting a secondary ray with functions such 
as mi_trace_reflection. The secondary ray will then obey the changed 
face flag. In mental ray 3.4 and later, it will be initialized to 0 by mental 
ray, so shaders can overwrite it but not read the default value. 


The variables in the next table are closely related to the previous. They describe the intersection 
of the ray with an object, and give information about that object and how it was hit. 


refraction_volume volume shader for refraction 
label object label for label file 
instance instance of object 
light_instance instance of light 


miTag 
miUint 
miTag 
miTag 
miScalar [4] 
miVector 
miVector 
miVector 
miCBoolean 
miScalar 
double 
double 
void * 

int 

double 
miScalar 
miScalar 


refraction_volume 


bary 


barycentric coordinates 


point intersection (ray end) point 
normal interpolated normal at point 
normal_geom geometry normal at point 


inv_normal true if normals were inverted 
dot_nd dot prod of normal and dir 


dist 


length of the ray 


material material of hit primitive 


pri 


identifies hit box 


pri_idx identifies hit primitive in box 
shadow_tol safe zone to prevent self-shadows 


1or 


index of refraction of medium 


ior_in index of refr. of previous medium 


The volume at the other side of the object. This is set to the volume 
shader of the material. It will be applied to refraction rays. This is 
implemented by copying refraction_volume to volume (which is 
the shader that gets called when the material shader returns) in the 
mi_trace_refraction and mi_trace_transparent functions. The 
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material shader may decide that the ray is leaving and not entering the 
object, and look in the state’s parents for an outside volume shader. 
This state variable is ignored in autovolume?* mode. 


label The label of the hit object. Every object may contain a label that is 
made available by this variable. When the primary material shader 
returns, the label is copied from the state to the “tag” frame buffer, 
if one was created by an appropriate output statement in the camera. 
The primary material shader is free to change this variable to any value 
to put different values into the tag frame buffer. 


instance The instance of the object containing the primitive hit by the ray. 


light instance If the ray is a light ray or the corresponding shadow ray: the light 
instance. If the ray hit a visible area light source, light_instance is 
set to that light instance. Until mental ray 3.1, this is the scene DAG 
instance that can also be found in shader parameters; in mental ray 
3.2 it is the leaf instance resulting from preprocessing and multiple 
instancing resolution (see m1_inclusive_lightlist). 


bary The three barycentric coordinates of the intersection in the hit 
primitive. The fourth value is reserved for implicit patches and is 
not currently used. Barycentric coordinates are weights that specify 
the contribution by each vertex or control point. The sum of all 
barycentric coordinates is 1. For hair, which is not based on triangles, 
the barycentric coordinates have a different meaning: bary[0] contains 
the parameter value along the width of the hair, with 0 at the left edge 
and 1 at the right edge’, with respect to the direction going from the 
root of the hair to the tip, and lying in the plane perpendicular to 
the ray direction; and bary[1] contains the parameter value along the 
length of the hair, with 0 at the first vertex defined, and 1 at the last. 


normal The (interpolated) surface normal at the intersection point if vertex 
normals are present, or the uninterpolated geometric normal of the 
primitive otherwise, in internal space. It points to the side of the 
primitive from which itis hit by the ray, and is normalized to within the 
precision of a float. Care should be taken when calculating the length 
of the normal; the result of this calculation might be very slightly 
greater than 1 because a float has only a little over six significant 
digits. This can cause math functions like acos to return NaN (Not a 
Number, an illegal result), which usually results in white pixels in the 
output if the NaN finds its way into a result color. 


normal_geom The uninterpolated normal of the hit primitive in internal space. It 
points to that side of the primitive from which it is hit by the ray. It is 
normalized. 


This was changed in mental ray 3.3. Previously, 0 was at the center of the hair and 1 at either edge, but this made it 
difficult to shade hair like tiny cylinders. 
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inv_normal 


dot_nd 


dist 


material 


pri 


priidx 


shadow_tol 
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If a ray hits geometry from behind (that is, if the dot product of 
the ray direction and the normal is positive), mental ray inverts both 
normal and normal_geom and sets inv_normal to miTRUE. This does 
not happen in shadow shaders, where dot_nd is undefined. 


The dot product of the normal and the direction (after the normals have 
been inverted in the case of backfacing geometry). In the case of light 
rays, it is the negative dot product of the light ray direction and the 
normal at the point which is to be illuminated. In a volume shader, dot- 
nd is undefined because there is no surface normal; however, mental 
ray 3.2 and later construct an artificial surface point to return a useful 
dot_nd value. 


The length of the ray, which is the distance from org to point if there is 
an origin, in internal space. A value lower or equal to 0.0 indicates that 
no intersection was found, and that the length is infinite. In output 
shaders, it is 0 for sequential shaders or the number of scanlines to 
write, beginning at raster_y, for parallel output shaders. 


The material of the primitive hit by the ray. (If a visible area light 
source has been hit, material is set to the inherited instance material, 
if available.) The data can be accessed using mi_db_access followed 
by mi_db_unpin. This is generally not necessary because all relevant 
information is also available in the state. 


This number uniquely identifies the current box. All primitives are 
grouped in boxes. When casting light rays, mental ray may check 
whether the primitive’s normal is pointing away from the light and 
ignore the light in this case; for this reason some shaders, such as 
ray marching volume shaders, assign 0 to pri before sampling a light. 
Shaders other than volume shaders should restore pr before returning. 
When a visible area light source is hit, pri is set to NULL. Some mi- 
query modes do not work if pri has been modified. 


Together with pri, this number uniquely identifies the primitive in the 
current box. This value is used by mental ray internally. 


If a shadow ray is found to intersect the primitive in shadow, at a 
distance of less than this tolerance, the intersection is ignored. This 
prevents self-shadowing in the case of numerical inaccuracies. 


This field is intended for use by material shaders that need to keep 
track of the index of refraction for inside/outside determination. It is 
not used by mental ray. The mi_mtl_refraction_index shader interface 
function stores the index of refraction of the medium the ray travels 
through in this state variable. 
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Like zor, this field helps the shader with inside/outside calculations. It 
contains the “previous” index of refraction, in the medium the ray was 
traveling through before the intersection. Like zor, zor_in is neither set 
nor used by mental ray, it exists to allow the material shader to inherit 
the previous index of refraction to subsequent shaders. 


3.4.5 Textures, Motion, Derivatives 


The following table is an extension to the previous. These variables give information about the 
intersection point for texture mapping. They are defined when the ray has hit a textured object: 


miVector * 
miVector * 
miVector * 


miVector 
miVector 
miVector 


tex _list 


bump x_list 


bump -y_list 


Lex 


motion 


texiiist 


bump_x_list 


bump_y_list 


tex 


motion 
derivs [5] 


list of texture coordinates 
list of X bump basis vectors 
list of Y bump basis vectors 
texture coord (tex shaders) 
interpolated motion vector 
list of surface derivatives 


A pointer to an array containing the texture coordinates of the 
intersection point in all texture spaces. When material shaders that 
support multiple textures on a surface call a texture lookup function, 
they must specify which texture coordinate to use, usually by choosing 
one of the texture vertices in tex_list and copying it to tex. In mental 
ray 3.4 texture spaces in miBox may have arbitrary dimension. tex_list 
entries contain only coordinates from up to three dimensional texture 
spaces. For higher dimensions, tex_list entries are set to zero and the 
function mi_texture_interpolate must be used instead. 


A pointer to an array containing the x bump basis vectors in all texture 
spaces. The vectors are in object space. The scene must have been 
prepared to contain or compute these vectors. They are very rarely 
used because normally shader compute the basis vectors on the fly. 


A pointer to an array containing the y bump basis vectors in all texture 
spaces. The vectors are in object space. 


The texture coordinates where the texture should be evaluated. This 
variable is available only in texture shaders; it is set by the caller (for 
example, a texture lookup from a material shader). 


The motion vector of the intersection point. If the object has no motion 
vectors (m statements in the vertices in the scene description file) 
or inherited motion transformations (including camera motion), the 
motion vector is a null vector. mental ray versions before 3.2 compute 
the motion vector only if there is a nonzero shutter interval; mental ray 
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3.2 and later always interpolate motion vectors if present. However, 
even mental ray 3.2 does not interpolate motion transformations if 
motion blurring is turned off, either with a zero shutter interval 
or a motion off statement’ in the options block, because of the 
performance implications. 


derivs[ | A pointer to an array containing the surface derivative vectors. It 
the object is a free-form surface object, the surface derivative vectors 
derivs[0] ... derivs[4] contain 0x/Ou, OX/Ov, 0?X%/Ou*, 0°x/Ov", 
0?x/Qudv, respectively. Here X denotes the intersection point. For 
polygonal objects the surface derivatives are taken from the .mi file. 
If the object has no first derivative vectors, the first two vectors are 
null vectors. If the object has no second derivative vectors, the last 
three vectors are null vectors. Since surface derivatives are calculated 
approximately, the vectors 0x/Ou, 0x/Ov and the normal vector at the 
intersection point are not necessarily orthogonal to each other. 


3.4.6 User Fields 


Finally, the user field allows a shader to store a pointer to an arbitrary data structure in the shader. 
Subsequent shaders called as a result of operations done by this shader (such as casting a reflection 
ray or evaluating a light or a texture) inherit the pointer and can read and write this shader’s local 
data. Sub-shaders can also find other parent’s user data by following state parent pointers, see 
above. With this method, extra parameters can be provided to and extra return values received 
from sub-shaders. 


However, once the shader that has set the user pointer returns, the user pointer is lost. Its purpose 
is to pass information to sub-shaders down the call graph, not to pass information from one 
invocation of a shader to the next (for example, to the next primary ray). This implies that it is 
not a good idea to use mi_mem_allocate to obtain the pointer because by definition this could 
result in millions of allocations, which is inefficient. Long-term shader user data should be stored 
in the shader user pointer (obtainable with the miQ_FUNC_USERPTR mode of mi_query) instead, 
typically allocated in the init shader and released in the exit shader. 


The user variables are initialized to 0. 


void * user user data pointer 


int user_size user data size (optional) 


The shader pointer can be used to access the shader parameters, as state—parameters. This is 
redundant for the current shader because this pointer is also passed as the third shader argument, 
but it can be used to find a parent shader’s parameters. 
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3.4.7. Options 


The option data structure pointed to by state — options has the following format, split here over 
three tables due to its size. The option structure may never be written to by shaders. 


int 
int 
miColor 


min_samples 
max_samples 
contrast 


minimum sampling level 
maximum sampling level 
sampling contrast 


time_contrast 
samplelock 
char render_space 


miColor 


temporal sampling contrast 
miBoolean 


noise animation locking on/oft 

coordinate space: ’c’ for camera space, ’o’ for 
object space 

rendered image rectangle size 

selective pixel sampling mode 

selective task sampling mode 

have visible area lights in the scene 
tessellation to strips and fans 


int task_size 
miCBoolean pixel_preview 
miCBoolean task_preview 
miCBoolean visible_lights 
miBoolean strips 


miCBoolean 
miCBoolean 
miCBoolean 
miCBoolean 
miUint1 
miTag 
miApprox 
miApprox 


miUinti 
float 
float 
miBoolean 
miBoolean 
miBoolean 
int 

float 
miColor 
int 
miPointer 
milmg_type 
miUint4 
miBoolean 
miTag 
miTag 


no_lens 
no_volume 
no_geometry 
no_displace 
no_output 
userdata 

approx 
approx_displace 
contour_contrast 
contour_store 
inh_funcdecl 
diagnostic_mode 
diag_photon_density 
diag_grid_size 


5X 


desaturate”’ 
dither’* 
nopremult>* 
colorclip’* 
gamma>* 
luminance_weight>* 
no_images 
image [ ] 
image_types [ ] 
write_imagel ] 
interp_imagel[ ] 
images_info°* 
foie’ 


disable lens shaders 
disable volume shaders 
disable geometry shaders 
disable displace shaders 
disable output shaders 
optional user data blocks 
approximation override 


displacement approximation override 


contour contrast shader 
contour store shader 


inheritance/traversal declaration 
miSCENE_DIAG_ flag bitmap 

density for diagnostic photon mode 
grid size for diagnostic grid mode 


fade to white, no clipping 


enable frame buffer dithering 


disable premultiplication 
color clipping modes 


frame buffer gamma value, 1 for none 
weights to calculate luminance 
highest frame buffer index plus 1 
frame buffers for output shaders 
image types of frame buffers 


bit 0: sample, bit 1: write 
interpolate frame buffer 
frame buffer information 
frame buffer directory 
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Rendering algorithm options: 


miBoolean trace ray tracing turned on? 


miBoolean scanline scanline mode turned on? 
miBoolean motion motion blur turned on? 

float shutter_delay”'! shutter open time for motion blur 
float shutter shutter close time for motion blur 
miCBoolean autovolume>* automatic volume management 


filter nonlocal sampling filter: ’b’ for box, ’t’ for 
triangle, ’g’ for Gauss, ’m’ for Mitchell, or 


’? for Lanczos 


char 


float filter_size_x filter size in x 
float filter_size_y filter size in y 
int reflection_depth max reflection trace depth 


int refraction_depth max refraction trace depth 


int trace_depth max combined trace depth 
char face f for front, ’b’ for back, or ’a’ for both faces 
char field ’o’ for odd or ’e’ for even fields, 0 for frames 


float 
char 


sample jittering: 0 for off, 1 for on 
0 for off, 1 for normal, ’s’ for segmented, ’l’ 
for sorted 

use shadow maps for rendering 

currently working on a shadow map rectan- 
gle 

recompute_shadowmaps | ’n’ for reuse, ’y’ for rebuild 
shadow_map_motion motion blurred shadowmaps 
acceleration ray tracing algorithm: ’b’ for BSP, ’g’ for grid 
grid_res[3]>"! grid resolution in world space: X, Y, Z 
grid_max_depth?'! maximum grid nesting 

grid_max_size>' maximum grid leaf size 

grid_max_size”! grid resolution correction 

space_max_size maximum BSP leaf size 

space_max_depth maximum BSP nesting 

space _max_mem maximum bsp memory in MB, 0 for unlim- 
ited 


jitter 
shadow 


char 
miCBoolean 


use_shadow_maps 
rendering _shadow_maps 


char 
miCBoolean 
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Global illumination options: 


int photon_reflection_ max photon reflection trace depth 
depth 

int photon_refraction_ 
depth 

int photon_trace_depth 
miTag photonmap_file 

miTag finalgather_file** 
miBoolean photonmap_rebuild 
miCBoolean finalgather_rebuild’* 
miBoolean caustic 
int caustic_accuracy 
float caustic_radius 


max photon refraction trace depth 


max combined photon trace depth 
photon map file name 

finalgather map file name 

rebuild photon map, don’t reuse 
rebuild final gather map 
caustics on/off 
number of caustic photons in estimate 
maximum distance for caustic photons in 
estimate 

filter constant for caustics 

caustic filter type: ’b’ for box, ’c’ for cone, 
’’ for Gauss 

default caustic flag for objects 
global illumination on/off 
number of globillum photons in estimate 
maximum distance for globillum photons in 
estimate 

default globillum flag for objects 
number of volume photons in estimate 
maximum distance for volume photons in 
estimate 
int finalgather final gathering: 0 for off, 1 for on, or ’f for 


float caustic_filter_const 
char caustic_filter 


miUint1l caustic_flag 
miBoolean globillum 
int globillum_accuracy 
float globillum_radius 


miUint1 globillum_flag 
photonvol_accuracy 


photonvol_radius 


fastlookup?* 

int finalgather_rays number of rays per final gather point 

float finalgather_maxradius | maximum distance between final gather 
points 

float finalgather_minradius | minimum distance between final gather 
points 


final gather radii are specified in raster pixels 
motion transformation path length 


miCBoolean finalgather_view™ 
miUint1l n_motion_vectors”'! 


min_samples The minimum oversampling level. 0 means one sample per pixel on 
average (mental ray actually samples corners, not centers of pixels). 1 
means subdivide once, which results in four subpixels. 2 means each 
subpixel is subdivided again, resulting in 16 subpixels, and so on. —1 
means one sample per four pixels, etc. 


max_samples After initial subdivision controlled by min_samples, pixels are further 
subdivided if the contrast demands it, up to the level determined by 
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contrast 


time_contrast 


samplelock 


render_space 


task_size 


pixel_ preview 


task_preview 


visible_lights 


strips 


no_* 


userdata 
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max_samples. 


If two neighboring samples are more different than the contrast, the 
pixel is subdivided unless the max_samples limit has been reached. 


Approximately an inverse to the number of time oversampling steps 
in motion blur rendering. 


If enabled, mental ray attempts to cast the same samples in each frame, 
which means that the grainyness due to low sampling stays in place, 
instead of flickering. This is achieved by not initializing sampling 
sequences with the frame number. This has an effect only where 
the image doesn’t change because otherwise oversampling will cast 
different samples. 


This is ’o’ for object space and ’c’ for camera space. Camera space 
rendering is supported for compatibility with mental ray 1.x, but not 
recommended for new scenes. 


The size of one image rectangle into which the image to render is 
subdivided. The default is 32 or 64. 


This is enabled during interactive rendering, where mental ray renders 
only those pixels that are affected by a user change, usually by tuning 
a shader parameter. 


This is enabled if the application has entered a mode where only certain 
image rectangles are rendered. 


This is true if there are any lights marked “visible” in the currently 
rendered scene. 


The tessellator will attempt to pack triangles into strips and fans. 
This is not useful for rendering with mental ray, and in fact incurs 
overhead due to strip and fan construction, but it can greatly improve 
the performance of OpenGL viewers. 


These flags disable lens, volume, geometry, displace, and output shader 
calls, respectively, or edge merging. They are useful for quick preview 
rendering. Shaders may still explicitly call the disabled shaders, but 
mental ray won’t. 


User data blocks are independent named toplevel scene entities that 
hold structured or unstructured data of any kind. Structured data is 
declared much like shader parameters, while unstructured data is a raw 
byte stream with a fixed size. User data is useful for large amounts of 
shared scene data. 
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approx 


approx_displace 


contour_contrast 


contour_store 


inh_funcdecl 


diagnostic_mode 


diag_photon_density 
diag _grid_size 


desaturate>* 


dither? * 
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May be set to any approximation method, which will override 
approximations specified in objects. This is useful for quick preview 
rendering where geometric precision does not matter. This is disabled 
if the method is set to miAPPROX_STYLE_NONE. 


This is the same as approx, but applies to displacement approximations 
in objects. 


The contour contrast shader, or 0. 
The contour store shader, or 0. 


The declaration of the inheritance function or traversal function*"!, or 


Q. 


If nonzero, enables various diagnostic modes that put false-color 
diagnostic data on top of the rendered image. The modes are: 


miSCENE_DIAG_SAMPLES shows where image samples were taken. 
miSCENE_DIAG_PHOTON_D shows photon density. 
miSCENE_DIAG_PHOTON_I shows photon irradiance. 
miSCENE_DIAG_GRID_O overlays object-space grid lines. 
miSCENE_DIAG_GRID_W overlays world-space grid lines. 
miSCENE_DIAG_GRID_C overlays camera-space grid lines. 
miSCENE_DIAG_BSP_D shows the BSP tree depth. 
miSCENE_DIAG_BSP_L shows the BSP leaf size. 

miSCENE_DIAG_FG°* shows final gather points. 

Calibrates the colors for the photon diagnostic modes. 

Determines the grid line distance in the grid diagnostic modes. 
Enables fading colors to white, instead of clipping individual com- 
ponents, when storing colors in 8-bit or 16-bit frame buffers. This 
and the following four fields used to be accessible with the miimg- 
getmode shader interface function in mental ray 2.1, but have moved 


into the options in mental ray 3.0. 


Enables dithering when storing colors in 8-bit or 16-bit frame buffers. 
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nopremult?* 


colorclip?* 


gamma>* 


luminance_weight>* 


no_images 


imagel | 
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Disables premultiplication, and stores unpremultiplied colors in frame 


buffers. 


Selects the color clipping mode applied when storing colors in 8-bit 
or 16-bit frame buffers, to make sure that RGB do not exceed alpha 
in premultiplication mode: 


miIMG_COLORCLIP_RGB preserves RGB and adjusts alpha if necessary. 


miIMG_COLORCLIP_ALPHA preserves alpha and adjusts RGB if neces- 
sary. 


miIMG_COLORCLIP_RAW disables color clipping. 


The gamma value applied when storing colors in 8-bit or 16-bit frame 
buffers. 1.0 disables gamma correction. 


The weights applied to RGB by the miluminance shader intertace 


function to compute a luminance value. 


The number of the highest defined frame buffer, plus 1. See image 


below for frame buffer numbers. 


An array of pointers to frame buffers. It is available only in output 
shaders. The type is miPointer to ensure network transparency, re- 
quiring access with image [i] .p; the real type is miImg_image *. The 
array is indexed with the predefined indices, each corresponding to 
one of the standard frame buffers that are enabled with appropriate 
output statements. If a frame buffer was not enabled, the correspond- 
ing pointer is 0. The predefined indices are: 


miRC_IMAGE_RGBA is the standard color image frame buffer. 
miRC_IMAGE_Z contains object depths. 

miRC_IMAGE_N contains normal vectors. 

miRC_IMAGE_M contains motion vectors. 

miRC_IMAGE_TAG contains object labels. 

miRC_IMAGE_COVERAGE?* contains coverage fractions of the object that 
contributed most to this pixel. If enabled, the Z, N, M, and TAG frame 


buffers contain values from that object. 


miRC_IMAGE_PPREV~"! contains shader bitmaps used for pixel preview- 
ing (interactive rendering). 
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miRC_IMAGE_USER is the first of the eight user frame buffers. The 
limitation to eight frame buffers has been removed in mental ray 3.4. 


All frame buffers have the same resolution as specified in the camera. 
The frame buffer pointers can be passed to the buffer access functions, 
mi_img_get_color, mi_img_put_color, etc. For each type of frame buffer, 
there are functions to retrieve and store a pixel value that accept the 
frame buffer pointer as their first argument. Motion vector data can 
be accessed with the normal-vector access functions; the data format 
is identical. 


In mental ray 3.4, the images field has been removed. See mi_output_image_open and mi_output- 
image-close. In addition, the arrays image_types, write image and interp_image are combined in 
the miFb_info structure. The database array of this structure is stored in zmages_info. 


image_types| | 


write image| | 


interp_image| | 


images_info 


Contains the type of each defined frame buffer. Removed in mental 
ray 3.4. 


For each defined frame buffer, bit 0 is set if the frame buffer is sampled, 
and bit 1 is set if the frame buffer is written. Removed in mental ray 
3.4. 


For each defined frame buffer, the flag is set if the frame buffer is 
interpolated (“+” was set in the scene) or aliased (“—” was set in the 


scene). Removed in mental ray 3.4. 


*4 An array of type miFb_info specifying the frame buffers. 


Rendering algorithm options in the state— options structure: 


trace 


scanline 


motion 


shutter 


If this flag is miTRUE, secondary ray tracing (reflection and refraction) 
is enabled. If it is miFALSE, only eye and transparency rays are 
evaluated, refraction rays degenerate to transparency rays, lens shaders 
cannot modify the ray origin and direction, and no shadows are 
computed regardless of the shadow flag. 


If this flag is mi TRUE, the scanline algorithm is enabled for primary 
rays. If scanline is miFALSE, primary rays are cast using pure ray 
tracing, which may slow down the rendering process. 


If this flag is miTRUE, motion blurring is enabled; if it is miFALSE, 
motion blurring is disabled even if motion vectors are present. 


If motion is set to miTRUE, the shutter determines the length of time the 
shutter is open, which controls the length of the blur. 1.0 means that 
the blur is as long as the motion vectors of motion transformations 
dictate. Values greater than 1.0 are not recommended because motion 
paths consisting of multiple motion 
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shutter_delay>'! 


autovolume* 


filter 


filter_size_x 


filter_size_y 


reflection_depth 


refraction_depth 


trace_depth 


face 


field 


jitter 
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If motion is set to miTRUE, the shutter delay determines the time the 
shutter opens. It closes at the shutter time, which must be equal to or 
greater than shutter_delay. A shutter range of 0...1 means that the blur 
uses the entire range of the motion vectors, motion path*', or motion 
transformations. 


If set, mental ray will keep track of which volumes a point is in. 
The shader can then use the shader interface functions mi_volume- 
num_shaders, mi_volume_cur_shader, mi_-volume_user-color, and m1_ 
volume_tags. 


Nonlocal filtering weighs samples according to their distance from the 
pixel center. Possible values are ’b’ for box, ’t’ for triangle, and ’g’ 
for gauss. 


Contains the filter width for collecting image samples into frame bufter 
pixels. 


Contains the filter height. 


The maximal allowed number of recursive reflections. A reflection 
ray will only by cast when this limit is not exceeded. If set to 0, no 
secondary reflection rays will be cast. See reflection_level above. 


The maximal allowed number of recursive refractions. A refraction ray 
will only be cast if this number is not exceeded. If set to 0, no secondary 
refraction or transparency rays will be cast. See refraction_level 
above. 


The maximal summed trace depth. mental ray will allow this many 
segments of the ray tree when it is followed through the scene, with any 
combination of reflections and refractions permitted by the previous 
two values until the total trace depth is reached. A ray will only be 
cast if this number is not exceeded. 


This variable specifies whether front-facing, back-facing, or all 
triangles are taken into account. All others are ignored, resulting in 
speed improvements. This is also called back face culling. The possible 
values are ’f’ (front), ?b’ (back), and ’a? (all). 


Field rendering, if turned on, renders only the even or odd scanlines 
of an image. Two successive renders are then combined to a full frame, 
resulting in smoother animations. 0 turns off field rendering, ’e’ 
renders only even scanlines (top is odd), and ’o’ renders only odd 
scanlines. 


If set to 1.0, jittering is enabled for samples smaller than a pixel. If set 
to 0.0, jittering is disabled. Other values are not legal. 
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shadow This ASCII character controls shadow casting. If it is 0, shadows 
are disabled (shadow off); if it is 1, normal shadows are computed 
in undefined order with volume shaders applied to the light ray 
(shadow on); if it is ?1’, shadow shaders are called in sorted order 
from the light source towards the illumination point (shadow sort); 
if it is ’s’, shadows are computed by tracing the segments between 
the illumination point, the occluding objects and the light source and 
applying volume shaders to these segments (shadow segment). 


use_shadow-_maps Enables shadow maps if set to miTRUE. 


rendering shadow_maps If set to miTRUE, mental ray is currently rendering a piece of a shadow 
map. Shaders will never see miTRUE because no shaders are called 
during shadow map rendering by mental ray 2.1 or 3.0. 


recompute_shadow_maps Ifsetto ’y’,shadow maps will be recomputed even if shadow map files 
were found. If set to ’n’, shadow map files will be used if available. To 
use shadow map files, the shadow-casting light sources must specify 
a shadow map file name. 


shadow_map_motion If set to miTRUE, shadow maps will contain object motion blur, which 
will extend the shadows in the direction of motion. 


acceleration The ray tracing algorithm. This is either ’b’ (a BSP algorithm), or ’ g’ 
(a hierarchical uniform grid algorithm only available in mental ray 2.1 
and 3.1 but not 3.0). Note that by default, primary rays are computed 
using a scanline algorithm if possible. 


grid_res{ }°! Controls the number of grid voxels in world space, in each dimension, 
if the acceleration algorithm is grid. 


grid_max_depth>:! Controls the number of levels of the grid tree, formed if a grid voxel 
of one level contains too much geometry and must be subdivided by 
a subgrid on a lower level. It has an effect only if the acceleration 
algorithm is grid. 

sae Controls the allowed complexity of a grid voxel before the voxel must 

be subdivided. It has an effect only if the acceleration algorithm is 

grid. If the grid_max_depth limit was reached, mental ray may exceed 

grid_max_size. 


grid_max_size 


re mental ray 2.1 had a different non-adaptive and non-recursive grid 


algorithm with only one parameter, a floating-point size that adjusts 
the resolution computed by mental ray. 1.0 accepts mental ray’s 
resolution estimate, larger values increase the resolution, and smaller 
values decrease it. It has an effect only if the acceleration algorithm is 


grid. 


grid_max_size 
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space_-max_depth?' 


space_Max_size 


space_max_mem 
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Controls the number of levels of the BSP tree, formed if a BSP voxel 
of one level contains too much geometry and must be subdivided by 
a subvoxel on a lower level. It has an effect only if the acceleration 
algorithm is BSP. 


Controls the allowed complexity of a BSP voxel before the voxel must 
be subdivided. It has an effect only if the acceleration algorithm is BSP. 
If the space_max_depth limit was reached, mental ray may exceed space- 
maxSize. 


Limits the memory used by the BSP tree to the specified number of 
megabytes. This is mostly an emergency brake because it may result 
in an unbalanced BSP tree. 


Global illumination options in the state—options structure: 


photon-_reflection_depth 


photon-_refraction_depth 


photon_trace_depth 


photonmap file 


finalgather file 


photonmap-_rebuild 


finalgather_rebuild 


caustic 


caustic_accuracy 


caustic_radius 


The maximal allowed number of recursive photon reflections. Similar 
to reflection_depth. Default is 5. 


The maximal allowed number of photon refractions. Similar to 
refraction_depth. Default is 5. 


The maximal summed photon trace depth. The maximum number of 
photon bounces is limited by this number. Default is 5. 


The name of the file where photon maps will be loaded and stored. 
This is a tag; the actual string can be accessed with mi_db_access. 


The name of the file where final gathering point maps will be loaded 
and stored. Note that unlike photon maps, final gather maps can be 
extended, and will grow over time unless periodically deleted. 


If set, the photon map file, if specified, will not be loaded, and 
the photon map is rebuilt from scratch. It will still be written if 


photonmap file is defined. 
If set, the final gather map file, if specified, will not be loaded, and 
the final gather map is rebuilt from scratch. It will still be written if 
finalgather file is defined. 


Specifies whether caustics are being simulated or not. 


The maximum number of photons to use when computing a caustic 
irradiance estimate. 


The radius around the current point in which the caustic irradiance 
estimate will look for photons. 
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caustic_filter_const 


caustic_filter 


caustic_flag 


globillum 


globillum_accuracy 


globillum_radius 


globillum_flag 


photonvol_accuracy 


photonvol_radius 


finalgather 


finalgather_rays 


finalgather_maxradius 


finalgather_minradius 


finalgather_view** 
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The falter constant for caustic estimates within the caustic radius. 


The type of filter to apply to the photons within the caustic radius: ’b’ 
for box, ’c’ for cone, or ’g’ for Gaussian. 


If bits 0 or 1 is set, all instances in the scene DAG will behave as if they 
had bit 0 or 1, respectively, set as well. Bit 0 enables photon casting 
and bit 1 enables photon reception. This is useful to make all objects in 
the scene contribute to photon tracing, if the scene was built without 
photon flags. Older scene creators may not know about these instance 
flags and leave them undefined. 


Specifies whether global illumination is being simulated or not. 


The maximum number of photons to use when computing a global 
illumination irradiance estimate. 


The radius around the current point in which the global illumination 
irradiance estimate will look for photons. 


The same as caustic_flag, except that it applies to global illumination, 
not caustics. 


The maximum number of photons to use when computing a volume 
. . . . . P . r 5 
global illumination irradiance estimate. 


The radius around the current point in which the volume global 
illumination irradiance estimate will look for photons. 


Specifies whether illumination is computed with final gathering. Final 
gathering can be combined with global illumination and caustics. 


The number of rays cast for each final gather point. mental ray 2.1 
always casts exactly this number, while mental ray 3.x have an adaptive 
optimizer that may decide to cast fewer rays than this number, but 
will never exceed it. 


The maximum distance between final gather points. If a final gathering 
estimate is needed and no final gather point is within this radius, a new 
final gather point is computed. 


The minimum distance between final gather points. Final gather points 
will be avoided if they would be closer than this to another final gather 
point. 


If set, this flag switches final gather radii to raster pixels instead of 
world space units. This causes final gathering to be view-dependent: 
distant objects will receive fewer final gather points than close objects. 
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Specifies the number of segments to be used for motion paths that 


approximate transformation motion. The default is 1; the maximum 
number is 15. Larger numbers allow transform motion paths that are 
more smoothly curved, but also reduce performance. 


n_motion_vectors>’ 


3.4.8 State Variables by Shader Type 


The following table describes which state variables are available in which types of shaders: 


G geometry shader 

D displacement shader 

P photon shader and photon volume shader 
E __ photon emitter shader 

Le lens shader 

M material shader and texture shader 

V____ volume shader 

Lg 

S 


light shader 
shadow shader 
Cs contour store shader 
a contour contrast shader and contour shader 


Lm __lightmap shader 
O output shader 
IE © shader init or exit function 


As an exception, a shader instance init function may use all the state variables that the shader 
itself may used. This does not apply to shader init functions, shader exit functions, and shader 
instance exit functions, all of which have only very limited access. 


In the table, 


r means that the shader may read this variable but should not modify it because it may have 
unknown effects on parent or child shaders. 


R means that the shader may read this variable but may never modify it because shader 
interface functions or other parts of mental ray depend on unchanged values. 


rw means that the shader may read or write this variable; if it writes it is good practice 
to restore the original contents before returning to avoid surprises in parent or volume 
shaders. pri, in particular, must be restored. Most shaders do not need to modify most of 
these. 


x means that the shader is free to read and write, and need not restore any values. These are 
“scratchpad” variables for shader communication, and not used by mental ray. 


~ means that the shader may neither read nor write this field. Its contents are undefined. 
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In the case of the options and camera variables, the shader may write neither the pointer nor any 
field of the options and camera structures. Note that during rendering (between the rendering 
and rendering finished messages), the camera and the options may differ from the scene file 
specifications because phenomenon requirements and conflict detection may make adjustments. 
For example, a lens shader might have requested ray tracing to be turned off even though it was 
turned on in the scene file. In this case, shaders called during rendering would see a trace flag that 
is off, and other shaders such as geometry or displacement shaders do not. 


version 

camera_inst 

camera 

options 

global_lock! rw 
raster_x 

raster_y 

parent 

type 


scanline 


‘arable —=«[G DPE 


reflection_level 
refraction_level 


face 

org 

dir 

dist 

time 

ior 

1or_in 
material 
volume 
environment 
refraction_volume 
label 

instance 
light_instance 
pri 

pri.dx 
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Ee, 


variable 
bary[4] 

point 

normal 
normal_geom 
dot_nd 
inv_normal 
shadow-tol 
tex_list 
bump-_x-_list 


bump-y_list 
motion 


Z 


4 


derivs 
tex 


shader 


bd x 

bd & 
ad ad ay 
as ad ay PM 
od ad ay PM 
ad ad ay XM 


bo | 
| 


user_size 


global_lock is accessed with mi_lock and mi_unlock only. 

If state — type is miRAY_SHADOW 

Set to 0 to cast rays from empty space. Do not set to other values. 
If the object contains surface derivatives 


-_ W bh 


See page 399 for a similar table listing available shader interface functions. 


3.5 Shader Parameter Declarations 


In addition to the state variables that are provided by mental ray and are shared by all shaders, 
every shader has shader parameters. In the .mi scene file, shader references look much like a 
function call: the shader name is given along with a list of parameters. Every shader call may 
have a different list of parameters. mental ray does not restrict or predefine the number and types 
of shader parameters, any kind of information may be passed to the shader. Typical examples 
for shader parameters are ambient, diffuse, and specular colors for material shaders, attenuation 
parameters for light shaders, and so on. An empty parameter list in a shader call (as opposed to a 
shader declaration) has a special meaning; see the note at the end of this chapter. 


In this manual, the term “parameters” refers to shader parameters in the .mi scene file; the term 
“arguments” is used for arguments to C functions. 


Shaders need both state variables and shader parameters. Generally, variables that are computed 
by mental ray, or whose interpretation is otherwise known to mental ray, and that are useful to 
different types or instances of shaders are found in state variables. Variables that are specific to 
a shader, and that may change for each instance of the shader, are found in shader parameters. 


3.5 Shader Parameter Declarations 227 


mental ray does not access or compute shader parameters in any way, it merely passes them from 
the .mi file to the shader when it is invoked. 


To interpret these parameters in the .mi file, mental ray needs a declaration of parameter names 
and types that is equivalent to the C struct that the shader later uses to access the parameters. 
The declaration in the .mi file must be exactly equivalent to the C struct, or the shader will mis- 
interpret the parameter data structure constructed by mental ray. (Using the mkmishader utility 
ensures that both declarations agree, see section 3.29.) This means that three parts are needed to 
write a shader: the .mi declaration, the C parameter struct, and the C source of the shader. The 
.mi declaration is normally stored in a separate file that is included into the .mi scene file using a 
$include statement. 


The syntax of .mi shader declarations is fully described in section 2.1. Here, only a brief overview 
is given. Shaders must be declared with shader name, return type, and the types and names of all 
parameters. Options such as the shader version may be specified also: 


declare shader 
[type] "shadername" ( 
type "parameter_name" , 
type "“parameter_name", 


type "parametername" 


[ version versionint | 
[ options | 
end declare 


For example, a simple material shader containing ambient, diffuse, and specular colors, 
transparency, an optional array of bump map textures, and an array of lights could be declared in 
the .mi file as: 


declare shader 
color "my_material" ( 


color "ambient", 
color "diffuse", 
color "specular", 
scalar "shiny", 

scalar "reflect", 
scalar "transparency", 
scalar ie > oie 

vector texture "bump", 

array light "lights" 


) 
version 1 
end declare 


If there is only one array, there is a small efficiency advantage in listing it last. It is recommended 
that the largest array (arrays of large structs are larger than arrays of primitives) is given as the 
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last parameter. The material shader declared in this example can be used in a material statement 


like this: 


material "mati" 
"mymaterial" ( 


“specular” 1.0 1.0 1.0, 
“ambient” 0.3 0.3.0.0, 
‘aitiuse”.. 0.7 0.7 -0«Q, 
"shiny" 50.0, 

"bump" Near © : 


"lights" Li *Lignti", “iienne", “Lignis” J, 
"reflect" 0.5 
) 


end material 


Note that the parameters can be defined in any order that does not have to agree with the order 
in the declaration, and that parameters can be omitted. Omitted parameters default to 0. This 
example assumes that the texture tex1 and the three lights have been defined prior to this material 
definition. Again, be sure to use the names of the textures and lights, not the names of the texture 
and light shaders. All names in the above two examples were written as strings enclosed in double 
quotes to disambiguate names from reserved keywords, and to allow special characters in the 
names that would otherwise be illegal. 


When choosing names, avoid double colons and periods, which have a special meaning when 
accessing structured shader return values and interface parameters in phenomenon subshaders. 


When the shader my_material is called, its third argument will be a pointer to a data structure 
built by mental ray from the declaration and the actual parameters in the .mi file. In order for the 
C source of the shader to access the parameters, it needs an equivalent declaration in C syntax 
that must agree exactly with the .mi declaration. The type names can be translated according to 
the following table: 


3.5 Shader Parameter Declarations 229 


boolean miBoolean 

integer milnteger 

scalar miScalar 

vector miVector 

transform miMatrix 

color miColor 

data miTag of an miUserdata 

shader miTag of an miFunction 

color texture miTag of an miFunction or milmg_image 
scalar texture miTag of an miFunction or milmg_image 
vector texture miTag of an miFunction or milmg_image 
light miTag of an milnstance for a light 

light miTag of an milnstance for a light group>? 
material miTag of an miMaterial 

geometry miTag of an miOlject, miGroup, or milnstance 
lightprofile*! miTag of an miLight_profile 

struct struct 

array int, int, type[1] 


A light group®” is an instance group that contains instances of lights. For the purpose of shading, 
the group is treated as if it were a single light. 


It is strongly recommended to use the same parameter names in the C declaration as in the .mi 
declaration. Also, structures in either declaration should be reflected in the other, even if not 
enclosed in arrays, to ensure that mental ray inserts the same padding as the C compiler. 


Arrays are more complicated than the types in this table because the size of the array is not 
known at declaration time. The C declaration of an array consists of a start index prefixed with 
i_, the size of the array prefixed with n_, and the array itself, declared as an array with one 
element. mental ray will allocate the structure as large as required by the actual array size at call 
time. To access array element z in the range 0...”_array — 1, the C expression array|i + 1_array| 
must be used. This expression allows mental ray to store the shader parameters in virtual shared 
memory regardless of the base address of the shader parameter structure, which is different on 
every machine on the network. 


Here is the C structure for the above example .mi declaration: 


struct my-material { 
miColor ambient; 
miColor diffuse; 
miColor specular; 
miScalar shiny; 
miScalar reflect; 
miScalar transparency; 
miScalar ior; 
mitag bump ; 
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int 1_lights; 
int n_lights; 
miTag lights [1]; 


ti 


Note that here the order of structure members must match the order in the .mi declaration exactly. 
For example, suppose a shader has a .mi declaration containing an array of integers: 


declare shader 
color "myshader" ( array integer "list" ) 
version 1 

end declare 


The C declaration for the shader’s parameters is: 


struct myshader { 
at. | 16 
int n_ List: 
miInteger list[1]; 
}; 


A shader that needs to operate on this array, for example printing all the array elements to stdout, 
would use a loop like this: 


int *list = mi_eval_integer(paras->list) ; 
int i_list = *mi_eval_integer(&paras->i_list) ; 
int n_list = *mi_eval_integer(&paras->n_list) ; 
int. iz 
for (i=0; i < n_list; i++) 

mi gntoC".0", tietli_list + ij); 


assuming that paras is the third shader argument and has type struct myshader *. The use of 
the i_list parameter may seem strange to C programmers, who may wish to hide it in a macro 


like 
#define EL(array,nel) array[i_##array + nel] 


This macro requires an ANSI C preprocessor; K&R preprocessors do not support the ## notation 
and should use /**/ instead. This macro is not predefined in shader.h. The reason for this peculiar 
way of accessing arrays is improved performance. The array list [1] has space for only one 
element, because the actual number of array elements depends on the shader instance in the .mi 
file, which may list an arbitrary number of elements. Since mental ray is based on a virtual shared 
database that moves pieces of data such as shader parameters transparently from one machine 
to another, no such piece of data may contain a pointer. Pointers would not be valid in another 
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machine’s virtual address space. Adjusting the pointer on the other machine is impractical because 
it would significantly reduce performance for some scenes, and would require knowledge of the 
structure layout for finding the pointers that may not be available in versions of mental ray not 
based on a .mi front-end parser. Therefore, the array is appended to the parameter structure, 
so the entire block can be moved to another machine in a single network transfer. It is safe to 
access the first element of the array, because space for it is always allocated by declarations such 
as list [1], but the second is a problem because in a C declaration like 


struct myshader { 
int 1 J4863 
int n_list; 
miInteger list[1]; 
miScalar factor; 
miBoolean bool; 


ie 


the second element, list [1], occupies the same address as factor, and the third overlays bool. 
The situation becomes more complex for arrays of structures. The solution is to put the value of 
the first element after the last “regular” shader parameter, bool in this example, followed by the 
other element values. This means that the first few C array elements that overlay other parameters 
must be skipped. The i_ variable tells the shader exactly how many. In the example, i_list would 
be 3. Consider the following shader instance, used as part of a material, texture, or some other 
definition requiring a shader call: 


"myshader" ( 
"factor" 1.4142136, 
MTien” (725.7 02S, “488024, 777 3] | 
"bool" on 
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The values of this shader instance will be arranged in memory like this: 


C declaration: Value: Value access: 


i_list 
n_list 
list[1] 


factor factor 


bool miTRUE bool 


list[i_list + 0] 


list[i_list + 1] 


list[i_list + 2] 


list[i_list + 3] 


On multithreaded machines, it is possible that any given shader runs in multiple threads 
simultaneously. When this happens, they share all static variables defined in the sources, all 
shader parameters, and the user pointer. The only things that are separate in separate threads are 
“auto” variables on the stack, and the state variables. Also, mental ray makes sure that an init 
shader runs once, in a single thread, before the actual shader runs in one or more threads. This 
makes init shaders the natural place to set up the shader user pointer, perhaps to store preprocessed 
shader parameters. See section 3.26.18 for more information on multithreaded shader design. 


Shaders should never write to shader parameters because they might be accessed by other threads 
or hosts or by future frames, and because shader and interface assignments might exist that would 
be destroyed. (In general, no shader should ever modify the scene.) 


3.6 Parameter Assignments and mi_eval 


The chapter on the .mi scene description language (page 60) explains assignment of shaders and 
phenomenon interface parameters to shader parameters. Assignments replace the constant value 
of a parameter with a link to a shader that gets called automatically when the shader asks for the 
value of the parameter, or a link to the phenomenon interface which is looked up, respectively. 


Shader assignments simplify the development of small, simple shaders called base shaders that 
can be combined into larger shaders or phenomena. For example, assignments make it possible 
to apply a texture to any shader parameter simply by replacing the constant value of a parameter 
with an assignment to a texture shader. It is no longer necessary for shader writers to anticipate 
which parameters should be texturable, and adding additional shader parameters of type color 
texture to the parameter list, just in case. 
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For example, consider this shader assignment example from page 69: 


declare shader 
color "phong" (color "ambient", 
color "diffuse", 
color "specular", 
scalar "shiny") 
version 1 
end declare 


declare shader 
strict, colder ..“a",..coler.."b"} 
"texture" (color texture "picture") 
version 1 
end declare 


color texture "fluffy" "/tmp/image.rgb" 


shader "map" "texture" ( 
"picture" ME LULL) 


shader "mtlsh" "phong" ( 


"shiny" 50, 
"ambient" Oo Use Ova, 
"diffuse" = "map.a", 
"specular" = "map.b") 


The author of the phong shader can focus on the purpose of the shader (Phong illumination) 
without having to consider texturing at all. The texture is applied later as a shader assignment to 
the parameters of phong. This example further illustrates that shaders may have structured return 
values, in this case in the shader texture which returns both a and b, which can be picked up 
individually using the dot-member notation. 


Frequently, shaders do not access all their parameters. Consider a multiplexing material shader 
that calls one of two material shaders depending on whether the incident ray hit the front face or 
the back face of the material. It would be very inefficient to evaluate both material shaders and 
then choose one of the two returned colors. For this reason, mental ray does not pre-evaluate all 
assignments before calling a shader. Instead, the shader itself must ask for the value of one of its 
parameters explicitly. This is done with the mz_eval function. The signature of mi_eval is 


void *mi_eval (miState *state, 

void *param ) 
miBoolean *mi_eval_boolean (miBoolean *param) 
miInteger *mi_eval_integer (miInteger »*param) 


miScalar *mi_eval_scalar (miScalar *param) 
miVector *mi_eval_vector (miVector *param) 
miScalar *mi_eval_transform (miScalar  *param) 
miColor *mi_eval_color (miColor *param) 


miTag xmi_eval_tag (miTag *param ) 
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The typed variants of mz_eval are implemented as macros that perform all necessary typecasting, 
as a convenience for shader writers. There are three cases handled by mi_eval: 


e If there is no assignment to the parameter whose address is passed, mi_eval simply returns 
that parameter. Being a macro, it can do so without measurable loss of performance. 


e Ifthe parameter is assigned to a shader, the shader will be called automatically and a pointer 
to the returned value is returned. If the shader was called before in the same context (such 
as the current phenomenon execution), the shader is not called again and a pointer to the 
cached previous result is returned. 


e Ifthe parameter is assigned to the interface of the phenomenon the shader is defined in, mz- 
eval returns a pointer to the value stored in the interface. 


In any case, the end result is that mi_eval returns a pointer to the parameter value, no matter 
where it comes from. If the shader accessed its parameters directly, without using mzi_eval, it 
would get garbage (such as 0 or NaN) if the parameter is assigned. For arrays, mi_eval must be 
applied to the array itself, as well as the i_array and n_array integers. Once the address of the 
array has passed through mz_eval, the array pointer is subscripted normally without applying mz_ 
eval to each element. This is a convention; only entire arrays should be assigned to other shaders 
or to the phenomenon interface if present, but not individual array members. 


For example, the phong shader in the example above would be implemented as: 


struct phong { 
miColor 
miColor 
miColor 
miScalar 


F3 


ambient ; 
diffuse; 
specular; 
shiny ; 


int phong_version(void) {return(1) ;} 


miBoolean phong( 
miColor 
miState 
struct phong 


miColor 
miColor 
miScalar 
int 
miTag 
milnteger 
miColor 
miColor 
miVector 
miScalar 
miScalar 


*result, 
*State, 
*paras) 


*diffuse; 
*specular ; 
shiny; 

nm, 2: 
*lights; 
samples; 
color; 
sum ; 

aay: 
dot_nl; 
spec_f; 


/* 
/* 
/* 


/* 
/* 
/* 
/* 
/* 
fa 
/* 
/* 
/* 
/* 
/* 


returned illum color */ 
ray tracer state */ 
phong parameters */ 


final diffuse param */ 
final specular param */ 
phong exponent */ 

light counter */ 

global light list */ 

# of samples taken */ 
color from light */ 
summed sample colors */ 
direction to light */ 
normal <dot> dir*/ 
specular factor */ 
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*xresult = *mi_eval_color (&paras->ambient) ; 

diffuse = mi_eval_color (&paras->diffuse) ; 

specular = mi_eval_color (&paras->specular) ; 
shiny = *mi_eval_scalar (&paras->shiny) ; 


mi_query (miQ_NUM_GLOBAL_LIGHTS, state, 0, &n); 
mi_query (miQ_GLOBAL_LIGHTS, state, 0, &lights); 


for (i=0; i <n; i++) { 
sum.r = sum.g = sum.b = QO; 
samples = 0; 


while (mi_sample_light(&color, &dir, &dot_nl, 
state, lights[i], 


&samples) ) 


{ 


spec_f = mi_phong_specular(shiny, state, 


sum.r += color.r * (dot_nl * 
spec_f * 
sum.g += color.g * (dot_nl * 
spec_f * 
sum.b += color.b * (dot_nl * 
spec_f * 


} 

if (samples) { 
result->r += sum.r / samples; 
result->g += sum.g / samples; 
result->b += sum.b / samples; 


} 
} 
result->a = 1; 
return (miTRUE) ; 


&dir) ; 
diffuse->r + 
specular->r) ; 
diffuse->g + 
specular->g) ; 
diffuse->b + 
specular->b) ; 


Note that mi_eval_color is called early to obtain pointers to parameters once. If there is a large 
number of lights, this saves a large number of mi_eval_color calls later. Although mi_eval et al. 
employ caching and fast lookups, this makes the shader faster than it were if the code were written 


like this: 


dot_nl * mi_eval_color (&paras->diffuse) ->r 


in the inner loop. 


3.7. Shader Versioning 


The parameter set of a shader must always be correctly described by its declaration in the .mi 
scene file. It is a common source of errors to have a mismatch between the .mi and the .c shader 
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parameters. This can lead to incorrect rendering results but can also cause shader crashes, for 
example if the shader mistakes a floating-point number for an array length. 


For this reason it is highly recommended to attach version numbers to both the .mi declaration 
and the shader itself. Version numbers are positive integers, and should begin with 1 (0 is the 
default if the version number is missing). For example, the .mi declaration of a shader myshader 
might be defined as: 


declare shader 
color "myshader" (parameters) 
version 42 

end declare 


There are two ways to ensure that the version number is correct. The recommended method is 
writing a pseudo-shader that provides the version number: 


DLLEXPORT int myshader_version(void) {return(42) ;} 


DLLEXPORT miBoolean myshader ( 


miColor *result, 
miState *State, 
struct myshader *paras) 
{ 
} 


Before mental ray calls a shader for the first time, just before looking for its initialization shader 
(whose name would be myshader_init), mental ray checks whether a function exists whose 
name is the shader name followed by _version. If it does, it is called and the version number is 
compared with the version number in the .mi declaration. If there is a mismatch, an error message 
is printed. If the version shader does not exist, a warning message is printed. 


The second method for shader version comparison is an explicit comparison in the shader using 
mi_query: 


#define MYSHADER_VERSION 42 


DLLEXPORT miBoolean myshader ( 
miColor *result, 
miState *state, 
struct myshader *paras) 


int version; 
mi_query(miQ_DECL_VERSION, state, 0, &version) ; 


if (version != MYSHADER_VERSION) 
mi_error("myshader: wrong declaration") ; 
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This method can be used to support several versions in a single shader implementation, but this 
is rarely necessary. Note that mental ray does not abort on a shader mismatch, which can lead to 
trouble later. 


It is very important to always increment the version number every time the shader parameters 
change. Problems introduced by mismatches are hard to find, especially if the shader versions 
on master and slave hosts do not agree. (Slaves always use the master’s declaration but their local 
libraries.) 


The following sections discuss the various types of shaders, and how to write custom shaders of 
those types. Basic concepts are introduced step by step, including supporting functions and state 
variables supplied by mental ray. All support functions are summarized at the end of this chapter. 


Most shader sources shown in this chapter were taken from the standard shader libraries, 
base.so, physics.so, and contour.so (.dll on NT). Shader sources are available on 
ftp://ftp.mentalimages.com/pub/. 


3.8 Material Shaders 


Material shaders are the primary type of shaders. All materials defined in the scene must at least 
define a material shader. Materials may also define other types of shaders, such as shadow, volume, 
photon, and environment shaders, which are optional and of secondary importance. 


When mental ray casts a visible ray, such as those cast by the camera (called primary rays) or 
those that are cast for reflections and refractions (collectively called secondary rays), mental ray 
determines the next object in the scene that is hit by that ray. This process is called intersection 
testing. For example, when a primary ray cast from the camera through the viewing plane’s pixel 
(100, 100) intersects with a yellow sphere, pixel (100,100) in the output image will be painted 
yellow. (The actual process is slightly complicated by supersampling and filtering, which can 
cause more than one primary ray to contribute to a pixel.) 


The core of mental ray has no concept of “yellow.” This color is computed by the material shader 
attached to the sphere that was hit by the ray. mental ray records general information about the 
sphere object, such as point of intersection, normal vector, transformation matrix etc. in a data 
structure called the state, and calls the material shader attached to the object. More precisely, 
the material shader, along with its parameters (called shader parameters), is part of the material, 
which is attached to or inherited by the polygon or surface that forms the part of the object that 
was hit by the ray. Objects are usually built from multiple polygons and/or surfaces, each of 
which may have a different material. 


The material shader uses the values provided by mental ray in the state and the variables provided 
by the .mi file in the shader parameters to calculate the color of the object, and returns that color. 
In the above example, the material shader would return the color yellow. mental ray stores this 
color in its internal sample list, which later gets filtered to compute frame buffer pixels, and then 
casts the next primary ray. Note that if the material shader has a bug that causes it to return 
infinity or NaN (Not a Number) in the result color, the infinity or NaN is stored as 1.0 in color 
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frame buffers. This results in white pixels in the rendered image. This is true for subshaders such 
as texture shaders also. 


With an appropriate output statement (see page 105), mental ray computes depth, label, normal- 
vector, and motion vector frame buffers in addition to the standard color frame buffer, and 
up to eight user frame buffers defined with frame buffer statements in the options block. 
The color returned by the first-generation material shader is stored in the color frame buffer 
(unless a lens shader exists; lens shaders also have the option of modifying colors). The material 
shader can control what gets stored in the depth, label, normal-vector, and motion-vector frame 
buffers by storing appropriate values into state — point.z, state — label, state — normal, and 
state —+ motion, respectively. It can also store data in the user frame buffers with an appropriate 
call to mi_fb_put. Depth is the negative Z coordinate in camera space. 


Material shaders normally do quite complicated computations to arrive at the final color of a 
point on the object: 


e The shader parameters usually include constant ambient, diffuse, and specular colors and 
other parameters such as transparency, and possibly optional textures that need to be 
evaluated to compute the actual values at the intersection point. If textures are present, 
texture shaders are called by using one of the lookup functions provided by mental ray. 
Alternatively, shader assignment may be used for texturing. Texture shaders are discussed 
in the next section. 


e The illumination computation sums up the contribution from various light sources listed 
in the shader parameters. To obtain the amount of light arriving from a light source, a 
light shader is called by calling a light trace or sample function provided by mental ray. 
Light shaders are discussed in a separate section below. After the illumination computation 
is finished, the ambient, diffuse, and specular colors have been combined into a single 
material color (assuming a more conventional material shader). 


e If the material is reflective, transparent, or using refraction, as indicated by appropriate 
shader parameters, the shader must cast secondary rays and apply the result to the material 
color calculated in the previous step. (Transparency is a variation of refractive transparency 
where the ray continues in the same direction, while refraction rays may alter the direction 
based on an index of refraction.) Secondary rays, like primary rays, cause mental ray to do 
intersection testing and call another material shader if the intersection test hit an object. 
For this reason, material shaders must be reentrant. In particular, a secondary refraction or 
transparency ray will hit the back side of the same object if face both is set in the options 
and the object is a closed volume. 


Note that the shader parameters of a material shader are under no obligation to define and 
use classical parameters like ambient, diffuse, and specular color and reflection and refraction 
parameters. Here is the source code of the mib_illum_phong shader in the standard base shader 
library: 


#include <stdio.h> 
#include <stdlib.h> /* for abs */ 
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#include <float.h> /* for FLT_MAX */ 
#include <math.h> 

#include <string.h> 

#include <assert.h> 

#include "shader.h" 


struct mib_illum_phong { 


miColor ambience; /* ambient color multiplier */ 
miColor ambient ; /* ambient color */ 

miColor diffuse; /* diffuse color */ 

miColor specular; /* specular color */ 

miScalar exponent ; /* shinyness */ 

int mode; /* light mode: 0..2 */ 

int i_light ; /* index of first light */ 

int n_light ; /* number of lights */ 

miTag light(1]; /* list of lights */ 


}; 
DLLEXPORT int mib_illum_phong_version(void) {return(2) ;} 


DLLEXPORT miBoolean mib_illum_phong( 


miColor *result, 
miState *State, 
struct mib_illum_phong *paras) 
{ 
miColor *xambi, *diff, *spec; 
miTag *light ; /* tag of light instance */ 
int n 1; /* number of light sources */ 
int af /* offset of light sources */ 
int m; /* light mode: O=all, 1=incl, 2=excl */ 
int ny /* light counter */ 
int samples; /* # of samples taken */ 
miColor color; /* color from light source */ 
miColor sum ; /* summed sample colors */ 
miVector dir; /* direction towards light */ 
miScalar dot_nl; /* dot prod of normal and dir */ 
miScalar expo; /* Phong exponent (cosine power) */ 
miScalar a /* amount of specular reflection */ 
ambi = mi_eval_color(&paras->ambient) ; 
diff = mi_eval_color(&paras->diffuse) ; 
spec = mi_eval_color(&paras->specular) ; 
expo = *mi_eval_scalar(&paras->exponent) ; 
m = *mi_eval_integer (&paras->mode) ; 
*xresult = *mi_eval_color(&paras->ambience); /* ambient term */ 


result->r *= ambi->r; 
result->g *= ambi->g; 
result->b *= ambi->b; 


n_l = *mi_eval_integer(&paras->n_light) ; 
i_l = *mi_eval_integer(&paras->i_light) ; 
light = mi_eval_tag(paras->light) + i_1; 
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if (m == 1) /* modify light list (inclusive mode) */ 
mi_inclusive_lightlist(&n_l, &light, state); 

else if (m == 2) /* modify light list (exclusive mode) */ 
mi_exclusive_lightlist(&n_l, &light, state); 


/* Loop over all light sources */ 
for (n-0;- n.< nel; mt, Lightt+) ¢ 
sum.r = sum.g = sum.b = 0; 
samples = 0; 
while (mi_sample_light(&color, &dir, &dot_nl, state, 
*light, &samples)) { 
/* Lambert’s cosine law */ 
sum.r += dot_nl * diff->r * color.r;: 
sum.g += dot_nl * diff->g * color.g; 
sum.b += dot_nl * diff->b * color.b; 


/* Phong’s cosine power */ 

S = mi_phong_specular(expo, state, &dir); 

if (s > 0.0) { 
sum.r += s * spec->r * color.r; 
sum.g += s * spec->g * color.g; 
sum.b += s * spec->b * color.b; 


} 
if (samples) { 


result->r += sum.r / samples; 
result->g += sum.g / samples; 
result->b += sum.b / samples; 


: 


/* add contribution from indirect illumination (caustics) */ 
mi_compute_irradiance(&color, state); 

result->r 4’ color, *« difti-or; 

result->g += color.g * diff->g; 

result->b += color.b * diff->b; 

result->a = 1; 

return (miTRUE) ; 


(From now on, code examples will omit #include statements and version functions. For 
information on writing and using a corresponding .mi language declaration, see the shader 
declaration chapter on page 60, or simply look at the base.mi file that comes with mental 


ray.) 


This shader first evaluates all its parameters because there are no paths through the code that 
do not require some parameters. This shader is concerned exclusively with computing a BRDF 
(bidirectional reflectance distribution function, here Phong) but not with reflections, refractions, 
transparency, textures, etc. The BRDF is implemented as a loop over all lights. Each light is 
sampled with an inner sample loop implemented with mi_sample_light, which takes care of area 
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light sources that require multiple samples. The contributions of each sample are summed, which 
produces the direct illumination component. Indirect illumination, computed by mi_compute- 
irradiance, is added at the end. 


Reflection and refraction can be added by another material shader that handles only refraction, 
and works with a BRDF material like the one above by assigning that shader to one of its inputs 
(here, the znput parameter). The following shader handles transparency (defined as transmission 
with an index of refraction of 1.0, refraction (an index other than 1.0), and total internal reflection. 
Total internal reflection happens for rays that hit the surface at a grazing angle; it is the reason 
why one sees the near part of the bottom of a pool, but at greater distances the water surface 
reflects the sky. 


struct mr { 


miColor input ; 
miColor refract; 
miScalar ior: 

Fj 

DLLEXPORT miBoolean mib_refract( 
miColor *result, 
miState *state, 
struct mr *paras) 

1 
miColor *refract = mi_eval_color(&paras->refract) ; 
miColor inp; 
miVector cir: 
miScalar ior; 


if (refract->r == 0.0 && refract->g == 0.0 && 
refract->b == 0.0 && refract->a == 0.0) 
*result = *mi_eval_color(&paras->input) ; 
else { 
ior = *mi_eval_scalar(&paras->ior) ; 
if (ior == 0.0 || ior == 1.0) 
mi_trace_transparent (result, state); 


else { 
if (mi_refraction_dir(&dir, state, 1.0, ior)) 
mi_trace_refraction(result, state, &dir); 
else { /* total internal reflection */ 
mi_reflection_dir(&dir, state); 
mi_trace_reflection(result, state, &dir); 
} 
} 
if (refract->r != 1.0 || refract->g != 1.0 || 


refract->b != 1.0 || refract->a != 1.0) { 
inp = *mi_eval_color(&paras->input) ; 
result->r = result->r * refract->r + 
inp.r *.(1.0 - refract->r) ; 
result->g = result->g * refract->g + 
inp.g * (1.0 - refract->g) ; 
result->b = result->b * refract->b + 
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inp.b * (1.0 - refract->b) ; 
result->a = result->a * refract->a + 
inp.a * (1.0 - refract->a) ; 


} 
return (miTRUE) ; 


Note that this shader evaluates its imput parameter only if the value is actually needed, to avoid 
wasting time computing a BRDF whose result is discarded. The ability to ask for parameter 
values explicitly is the reason for the mz_eval facility in mental ray. This shader makes this even 
more obvious: 


struct mt { 
miColor front; 
miColor back; 


}; 
DLLEXPORT miBoolean mib_twosided( 
miColor *result, 
miState *state, 
Struct. nt *paras ) 
{ 
if (state->inv_normal) 
*result = *mi_eval_color(&paras->back) ; 
else 
*xresult = *mi_eval_color(&paras->front) ; 
return (miTRUE) ; 
} 


This shader can be used as a material shader that applies different materials to the front and 
back side of an object. Front and back are determined by the direction of the normal vector. The 
two materials are simply assigned to the front and back parameters. Clearly, it would be very 
inefficient if this shader evaluated both its inputs. 


Bump mapping is another common function of material shaders. It involves altering the normal 
vector before computing the BRDKF, because the normal determines the surface orientation and 
is essential to BRDF computation. Here is a bump map shader that computes and returns a new 
normal vector: 


struct mib_bump_map_simple { 


miVector u; 
miVector v: 
miVector coord; 
miVector step; 
miScalar Lactor; 
miTag tex; 
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DLLEXPORT miBoolean mib_bump_map_simple( 


miVector *result, 

misState *State, 

struct mib_bump_map_simple *paras) 

{ 

miTag tex = *xmi_eval_tag (kparas->tex) ; 

miVector coord = *mi_eval_vector (&paras->coord) ; 

miVector step = *mi_eval_vector (&paras->step) ; 

miVector u = *mi_eval_vector (&paras->u) ; 

miVector Vv = *mi_eval_vector (&paras->v) ; 

miScalar factor = *mi_eval_scalar (&paras->factor) ; 

miVector coord_u, coord_v; 

miScalar val, val_u, val_v: 

miColor color: 

coord_u.x = coord.x + (step.x ? step.x : 0.001); 

coord_u.y = coord.y; 

coord_u.z = coord.zZ; 

coord_v.x = coord.x; 

coord_v.y = coord.y + (step.y ? step.y : 0.001); 

coord_v.z = coord.zZ; 

if (!tex || !mi_lookup_color_texture(&color, state, tex, &coord)) { 

*result = state->normal; 
return (miFALSE) ; 

} 

val = (color.r + color.g + color.b) / 3; 

mi_flush_cache(state) ; 

val_u = mi_lookup_color_texture(&color, state, tex, &coord_u) 
7 (color.r + coler.@ + caler.b) / 3 : wal; 

mi_flush_cache(state) ; 

val_v = mi_lookup_color_texture(&color, state, tex, &coord_v) 
? (color.r + color.g + color.b) 7 3 : val; 

val_u -= val; 

val_v -= val; 

state->normal.x += factor * (u.x * val_u + v.x * val_v); 

state->normal.y += factor * (u.y * val_u + v.y * val_v); 

state->normal.z += factor * (u.z * val_u + v.z * val_v); 

mi_vector_normalize(&state->normal) ; 

*result = state->normal; 

return (miTRUE) ; 

} 
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This is a simplified version of the mib_bump_map shader in the base library that lacks some 
nonessential projection features. It looks up a texture map at the current point and one point 
above and to the side each, and perturbs the normal vector depending on the differences between 
these sampling points. Here a shader assignment of the texture would not work because that 
would generate the same result three times. 


Moreover, it is necessary to call mi_flush_cache to turn off mental ray’s result caching, which 
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normally prevents a shader to be called multiple times if it is evaluated multiple times. This 
happens frequently, for example when a texture shader is assigned to both the ambient and 
diffuse parameters of a BRDF material shader — obviously it would be inefficient to compute the 
same texture twice when the BRDF shader evaluates both parameters, so the second evaluation 
simply causes mental ray to return the cached result from the first evaluation. Here this would 
defeat the purpose, so the cache must be cleared explicitly. 


The following shader is a variation on the first. Instead of returning a vector, it leaves the return 


value unchanged, but still modifies the state — normal state variable that BRDF functions use 
for illumination calculations: 


DLLEXPORT miBoolean mib_passthrough_bump_map_simple( 


miColor *result, 
miState *State, 
struct mib_bump_map_simple *paras) 
{ 
miVector dummy ; 
return(mib_bump_map_simple(&dummy, state, paras)); 
I 


This way, the shader can simply be inserted in a shader list, as in 


material "mtl1" 
"mib_passthrough_bump_map_simple" () 
"mib_illum_phong" (...) 

end material 


mental ray will first call the bump passthrough shader, which perturbs state — normal, and then 


the Phong shader, which uses the normal. Since the passthrough bump shader does not alter its 
result, the end result is the BRDE 


Texturing can be handled by calling shader API functions such as milookup_color_texture in the 
material (or other) shaders, but it is easier to simply assign a texture shader to one of the BRDF 
color inputs, especially ambient and diffuse in the Phong example above. 


Hair*' material shaders work like normal material shaders, with a few changes in the state: 


e bary([0] contains the parameter value along the width of the hair, with 0 at the left edge and 
1 at the right edge, with respect to the direction going from the root of the hair to the tip, 
and in a plane perpendicular to the incoming ray. 


e bary[1] contains the parameter value along the length of the hair, with 0 at the first vertex 
defined, and 1 at the last. 


e normal_geom is the tangent of the first segment of the hair. This is an approximation to the 
normal at the “scalp”, and can be useful for certain shading models. 
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e normal is the interpolated normal facing the ray direction. 
e derivs[0] is the interpolated tangent at the point of intersection. 


e tex_list contains texture scalars in the order [0].x, [0]-y, [0].z, [1].x, and so on. This is 
equivalent to the way other geometry stores texture data, except that hair uses scalars, not 
vectors, and their number does not have to be a multiple of three. It is often useful to recast 
tex_list to amiScalar pointer. 


Hair material shaders should not normally assume that hair consists of geometrical cylinders that 
can be shaded normally, complete with a terminator and all. Hair is too fine for shading around 
the circumference; any attempt to place highlights on just one side of the hair may cause aliasing. 
The base shader library shipped with mental ray contains a special hair material shader mib_ 
illum hair tor this purpose. 
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Texture shaders evaluate a texture and typically return a color, scalar, or vector (but like any shader, 
return values can be freely chosen and may even be structures of multiple values). Textures can 
either be procedural, for example evaluating a 3D texture based on noise functions or calling other 
shaders, or they can do an image lookup. The .mi format provides different texture statements 
for these two types, one with a function call and one witha texture file name. Refer to section 2.7.3 
for details. 


Texture shaders are not first-class shaders. This means that mental ray never calls one by itself 
and provides no special support for them. Texture shaders are called exclusively by other shaders. 
There are four ways of calling a texture shader from a material shader or other shaders: either 
by simply calling the shader by name like any other C function, or by requesting the value of 
a shader parameter using mi_eval (the recommended method, see below), or by using a built-in 
convenience function like milookup-_color_texture, or with a statement like 


mi_call_shader_x(result, miSHADER_TEXTURE, state, tag, args); 


The tag argument references the texture function. The texture function is a data structure in the 
scene database that contains a reference to the C function itself, plus a pointer to a user argument 
block arg that is passed to the texture shader when it is called. User arguments are rarely used, 
and mi_call_shader_x is the only way to pass them to a shader. Although the texture shader could 
also be called directly with a statement such as 


mib_texture_lookup(result, state, &paras) ; 


the caller would have to write the required arguments into the user argument structure soft- 
color_paras itself; it would not have access to shader parameters specified in the .mi file. The 
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recommended way of calling subshaders is implicitly with mi_eval, which does not require the 
calling shader to be aware that a subshader provides the value. This makes shaders very flexible 
by allowing them to be combined in arbitrary ways from the scene file, without changing and 
recompiling shader sources. However, there are cases when not the value of a shader but a shader 
itself is passed as a parameter, and mi_call_shader_x provides a good way of calling such shaders. 


Unlike material shaders, texture shaders usually return a simple color or scalar or other return 
value. There are no lighting calculations or secondary rays. This greatly simplifies the task of 
changing a textured surface. For example, a simple texture shader that does a simple, non- 
antialiased lookup in a texture image could be written as: 


struct mib_texture_lookup { 


miTag tex; 
miVector coord; 
}; 
DLLEXPORT miBoolean mib_texture_lookup( 
miColor *result, 
miState *state, 
struct mib_texture_lookup *paras) 
{ 
miTag tex = *mi_eval_tag(&paras->tex) ; 
miVector *coord = mi_eval_vector(&paras->coord) ; 
if (tex && coord->x >= 0 && coord->x < 1 
&& coord->y >= 0 && coord->y < 1 
&& mi_lookup_color_texture(result, state, tex, coord)) 
return (miTRUE) ; 
result->r = result->g = result->b = result->a = 0; 
return (miFALSE) ; 
} 


This shader can be assigned to parameters of another shader, such as a material shader, causing 
that shader to see textured color inputs without having to implement texturing itself. Here is an 
example scene fragment: 


color texture "texfile" "/some/directory/imagefile.rgb" 
shader "coordshader" "mib_texture_vector" (...) 


shader "texshader" "mib_texture_lookup" ( 
"coord" = "coordshader" 
"tex" "texfile") 


material "mtl" 
"mib_illum_phong" ( 
"ambient" = "texshader", 
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"diffuse" = 
e 


end material 


"texshader", 


247 


Note that texshader is defined here as a named shader because it is going to be assigned in the 
material. Instead of using a file texture for the tex parameter, another shader, perhaps a procedural 
marble shader, could have been used. The texture shader needs to know which point on the texture 
to look up, as a vector assigned to the coord parameter. Coordinate lookups are a very flexible 
way to implement all sorts of projections, wrapping, scaling, replication, distortion, cropping, 
and many other functions, so this is also implemented as another shader. It could be done inside 
the texture lookup shader itself, but separating it out into a separate shader allows all those 
projections and other manipulations to be implemented only once, instead of in every texture 
shader. Here is an example of a texture projection shader like mib_texture_vector used in the 
example above (simplified because the full shader is 235 lines): 


#define TP_NONE 
#define TP_XY 
#define TP_XZ 
#define TP_YZ 
#define TP_SPHERE 


#define TS_INTERNAL 
#define TS_OBJECT 
#define TS_WORLD 
#define TS_CAMERA 
#define EPS 


struct uv {miVector 


0 /* texture/bump-basis vector projection */ 
2 

3 

4 

5 

0 /* texture coordinate spaces (selspace) */ 
1 

2 

3 

1le-4 

u, v3s; 


struct mib_texture_vector_simple { 


milnteger 
milnteger 


ri 


DLLEXPORT miBoolean 
miVector 
misState 


selspace; 
project; 


mib_texture_vector_simple( 
*result, 
*state, 


struct mib_texture_vector_simple *paras) 


miVector 
miVector 
miVector 
miInteger 
miInteger 
miBoolean 


V; /* working vector */ 

*VD; /* pointer to working vector */ 
tmp, *tril3]; /* temporaries */ 

selspace = *mi_eval_integer (&paras->selspace) ; 
project; 

SUCCeSS; /* is mapping successful */ 


project = *mi_eval_integer (&paras->project) ; 
vp = &state->point ; 
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if (selspace && state->time != 0) { 
V.X = vp->x + state->motion.x * state->time; 
V.y = vp->y + state->motion.y * state->time; 
V.Z = vp->z + state->motion.z * state->time; 
vp = &v; 

t 

switch(selspace) { 

case TS_OBJECT: 

mi_point_to_object(state, &v, vp); 
vp = &v; 
break; 


case TS_WORLD: 
mi_point_to_world(state, &v, vp); 
vp = &v; 
break; 


case TS_CAMERA: 
mi_point_to_camera(state, &v, vp); 
vp = &v; 
break; 
t 
success = miTRUE; 
switch(project) { 


case TP_XY: 
V.X = Vp->x; v.y = vp->y; v.z = 0; 
vp = &v; 
break; 

case TP_XZ: 
V.X = vp->x; v.y = vp->z; v.z = 0; 
vp = &v; 
break; 

case IP_YZ: 
V.X = vp->y; v.y = vp->z; v.z = QO; 
vp = &v; 
break; 


case TP_SPHERE: { 
float length; 
length = mi_vector_norm(vp) ; 
/* put seam in x direction */ 
if (!vp->z && !vp->x) { 
/* singularity point */ 
v.x = 0.0; 
Success = miFALSE; 
} else 
vV.x = atan2(-vyp->2, vp->x) / M_P1I-/ 2; 


if (v.x < 0) v.x += 1; 
/* y comes from asin */ 
if (length) 
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v.y = asin(vp->y / length) / M_PI + 0.5; 


else 
v.y = 0.5f; 
v.z = QO; 
vp = &v; 
break; } 


} 

*result = *vp; 
Sstate->tex = *result; 
return(success) ; 


This shader only picks up a vector, here from state — point but the full shader has several 
other methods. The complete shader has more methods for picking up vectors, especially from 
state — tex, which is a variable that is commonly used to pass texture lookup coordinates to a 
texture shader. The mz_lookup_color_texture function does this, for example. 


Remapping, including scaling, rotation, cropping, replication, etc., is handled by yet another 
shader (mib_texture_remap), not shown here. Refer to ftp: //ftp.mentalimages.com/pub/ for 
the full source code. This was done to keep the base shader library as flexible as possible, although 
in practice higher performance can be achieved by writing shaders that perform coordinate lookup 
and remapping in a single shader. 


Finally, here is a shader that uses full elliptical filtering for better texture anti-aliasing, especially 
of textures seen at a sharp angle: 


struct mib_texture_filter_lookup { 


miTag tex; 

miVector coord; 

miScalar eccmax; 

miScalar maxminor ; 

miScalar dis¢.r; 

miBoolean bilinear; 

miUint space; 

miTag remap ; 
}; 
#define DISC_R 0.3 /* projection matrix circle radius */ 
#define CIRCLE_R 0.8 /* projected screen-space circle */ 


DLLEXPORT miBoolean mib_texture_filter_lookup( 


miColor *result, 
miState *state, 
struct mib_texture_filter_lookup *paras) 
t 
miTag tex = *mi_eval_tag(&paras->tex) ; 
miVector *coord; 
miUint space; 
miTag remap ; 


miVector pis), ela); 
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miMatrix SIs 

miTexfilter ell_opt; 

miScalar disc_r; 

if (!tex) { 
result->r = result->g = result->b = result->a = 0; 
return (miFALSE) ; 

te 

coord = mi_eval_vector(&paras->coord) ; 

Space = *mi_eval_integer (&paras->space) ; 


disc_r = *mi_eval_scalar(&paras->disc_r) ; 
if (disc_r <= 0) 
disc_r = DISC_R; 
if (state->reflection_level == 0 && 
mi_texture_filter_project(p, t, state, disc_r, space) && 
(remap = *mi_eval_tag(&paras->remap))) { 
mi_call_shader_x((miColor*)&t[0], miSHADER_TEXTURE, 
state, remap, &t[0]); 
mi_call_shader_x((miColor*)&t[1], miSHADER_TEXTURE, 
state, remap, &t[1]); 
mi_call_shader_x((miColor*)&t [2], miSHADER_TEXTURE, 
state, remap, &t[2]); 
if (mi_texture_filter_transform(ST, p, t)) f{ 


ell_opt.eccmax = *mi_eval_scalar (&paras->eccmax) ; 
ell_opt.max_minor = *mi_eval_scalar(&paras->maxminor) ; 
ell_opt.bilinear = *mi_eval_boolean(&paras->bilinear) ; 


ell_opt.circle_radius = CIRCLE_R; 
ST([2*4+0] = coord->x; 
ST[2*4+1] = coord->y; 
if (mi_lookup_filter_color_texture(result, state, 
tex, kell_opt, ST)) 
return (miTRUE) ; 
t 
} 
/* fallback to standard pyramid or nonfiltered texture lookup */ 
return(mi_lookup_color_texture(result, state, tex, coord)); 


This shader is based on calling a texture shader multiple times to derive gradients that can be passed 
to mi_texture_filter_transform, and otherwise passing shader parameters to mi_lookup_filter_color- 
texture, which handles the elliptical lookup. For more information on elliptical texture lookups, 
refer to the base shader documentation. 


3.10 Volume Shaders 


Volume shaders may be attached to the camera or to a material. They modify the color returned 
from an intersection point to account for the distance the ray traveled through a volume. The 
most common application for volume shaders is atmospheric fog effects; for example, a simple 
volume shader may simulate fog by fading the input color to white depending on the ray distance. 
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By definition, the distance dist given in the state is 0.0 and the intersection poznt is undefined if 
the ray has infinite length. 


Volume shaders are normally called in three situations. When a material shader returns, the volume 
shader that the material shader left in the state—volume variable is called, without copying the 
state, as if it had been called as the last operation of the material shader. Copying the state is not 
necessary because the volume shader does not return to the material shader, so it is not necessary 
to preserve any variables in the state. 


Unless the shadow segment mode is in effect, volume shaders are also called when a light shader 
has returned; in this case the volume shader state—volume is called once for the entire distance 
from the light source to the illuminated point (i.e., to the point that caused the material shader 
that sampled the light to be called). In shadow segment mode, volume shaders are not called for 
light rays but for every shadow ray segment from the illuminated point towards the light source. 
Some volume shaders may decide that they should not apply to light rays; this can be done by 
returning immediately if the state—type variable is miRAY_LIGHT. 


Finally, volume shaders are called after an environment shader was called. Note that if a volume 
shader is called after the material, light, or other shader, the return value of that other shader is 
discarded and the return value of the volume shader is used. The reason is that a volume shader 
can substitute a non-black color even if the original shader has given up. Volume shaders return 
miFALSE if no light can pass through the given volume, and miTRUE if there is a non-black result 
color. 


Material shaders have two separate state variables dealing with volumes, volume and refraction-_ 
volume. If the material shader casts a refraction or transparency ray, the tracing function will 
copy the refraction volume shader, if there is one, to the volume shader after copying the state. 
This means that the next intersection point finds the refraction volume in state—volume, which 
effectively means that once the ray has entered an object, that object’s interior volume shader 
is used. However, the material shader is responsible to detect when a refraction ray exits an 
object, and overwrite state—refraction_volume with an appropriate outside volume shader, such 
as state—-camera—volume, or a volume shader found by following the state—parent links. 


Since volume shaders modify a color calculated by a previous material shader, environment 
shader, or light shader, they differ from these shaders in that they receive an input color in the 
result argument that they are expected to modify. A very simple fog volume shader could be 
written as: 


miBoolean myfog( 


register miColor *result, 
register miState *state, 
register struct myfog *paras) 

{ 
register miScalar fade; 
register miColor *fogcolor; 
register miScalar max ; 


if (state->type == miRAY_LIGHT) 
return (miTRUE) ; 
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max = *mi_eval_scalar(&paras->maxdist) ; 
fogcolor = mi_eval_scalar(&paras->fogcolor) ; 
fade = state->dist > max ? 1.0 


state->dist / max; 


result->r = fade * fogcolor->r 
+ (1-fade) * result->r; 
result->g = fade * fogcolor->g 
+ (1-fade) * result->g; 
* 
* 
* 
* 


result->b = fade fogcolor->b 


+ (1-fade) result->b; 
result->a = fade fogcolor->a 

+ (1-fade) result->a; 
return (miTRUE) ; 


This shader linearly fades the input color to state—fogcolor (probably white) within 
state—maxdist internal space units. Objects more distant are completely lost in fog. The length 
of the ray to be modified can be found in state—-dist, its start point in state—org, and its end point 
in state—point. This example shader does not apply to light rays, light sources can penetrate fog 
of any depth because of the miRAY_LIGHT check. In this case, the shader returns miTRUE anyway 
because the shader did not fail; it merely decided not to apply fog. Note that the shader parameters 
are evaluated with mzi_eval after the if statement to ensure that no unnecessary work is done by 
obtaining parameter values that are not going to be used. 


If this shader is attached to the camera, the atmosphere surrounding the scene will contain fog. 
Every state—volume will inherit this camera volume shader, until a refraction or transparency 
ray is cast. The ray will copy the material’s volume shader, state—refraction_volume, if there is 
one, to state—volume, and the ray is now assumed to be in the object. If the material has no 
volume shader to be copied, the old volume shader will remain in place and will be inherited by 
subsequent rays. 


Some volume shaders employ ray marching techniques to sample lights from empty space, to 
achieve effects such as visible light beams. Before such a shader calls mi_sample_light, it should 
store 0 in state—pri to inform mental ray that there is no primitive to illuminate, and to not 
attempt certain optimizations such as backface elimination. Shaders other than volume shaders 
may do this too, but must restore pri before returning. Some mi_query modes do not work if pri 


has been modified. 


Volume shader that sample light sources should not only clear state—pri but also use this test at 
the beginning: 


if (state->type == miRAY_LIGHT) return(miTRUE) ; 


Since sampling a light causes one or more light rays to be cast, and since these light rays most 
likely travel through the same volume, they would also call this same volume shader recursively. 
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If the volume shader doesn’t realize this and proceeds to cast even more recursive rays, it will 
get into an infinite recursion until a stack overflow aborts the program. Note that the test should 
come before all other code, especially mi_eval calls, to avoid unnecessary work and increase 
performance. 


3.11 Volume Shaders Using Autovolume> 


mental ray 3.0 offers a new volume tracking mode called autovolume. In this mode, mental ray 
keeps track of which volumes a ray is in, manages nested volumes, keeps track of which volumes 
the camera is in, and takes over inside/outside decisions. This allows scenes with overlapping 
volumes such as light cones from street lights, even if the camera moves through the light cones in 
an animation. With mental ray 2.1, sophisticated volume shaders would be required for handling 
this correctly. 


In autovolume mode, the volume shader attached to the camera controls the volume of the 
world outside all other object volumes, and necessarily the volume that the camera is in. Volume 
shader declarations may specify a volume level greater than zero that defines the properties of 
the volume: volumes at higher levels displace volumes at lower levels, and volumes at equal levels 
mix. The default level is 1. Mixing means that if a ray travels through such a volume, all volume 
shaders at the highest level are called, and all lower levels are ignored. Levels are defined in the 
shader declaration (see page 227): 


declare shader 
color "volume_shader_name" (...) 
volume level 1 

end declare 


Each volume shader has the option of terminating the chain of mixed volume shaders scheduled 
for execution. For example, a volume shader that creates a swirl of particles may allow other 
shaders to be called to add their particles, but a plain fog shader might terminate the list to 
prevent the fog to be twice as dense where two fog volumes intersect. 


To activate autovolume mode, the following options are required: 


scanline off for mental ray 3.2 and earlier, because scanline intersections were not 
reliable; 3.3 and higher have no problems. 


volume on to turn on volume shading (this is the default), 
autovolume on to switch to autovolume shading, and 
shadow segments because shadow segments are required to keep track of shadow rays 


passing through volumes. 


It is not necessary to turn on raytracing. After activating autovolume, old volume shaders can 
still be used. However, state — volume and state — refraction_volume are ignored by mental ray 


254 3 Using and Writing Shaders 


since inside/outside determination is now done internally. Shaders can detect autovolume mode 
by checking state — options — autovolume. 


To help the shader writer merge results of individual volume shaders called on a ray, mental ray 
3.x provides functions for limited communication between these shaders: 


mi_volume_num-shaders returns the total number of shaders that mental ray is going call for this 
ray segment. 


mi_volume_cur_shader returns the relative index of the current shader, ranging from 0 to mi_ 
volume_num-_shaders — 1. 


mi_volume_tags returns a const pointer to an array of volume shader tags that mental ray calls for 
this ray segment. 


mi_volume_user-color returns the pointer to a user-defined color which can be used to accumulate 
shader results. mental ray does not touch this value. 


When mental ray has collected all the shaders to call for a given volume, there are three principally 
different ways how results of individual volume shaders can be combined: 


e By user color: the first shader (where mi_volume_cur_shader returns (0) initializes the user 
color. All remaining shaders contribute their results by modifying the user color. The last 
shader (where mi_volume_cur_shader returns mi_volume_num_shaders — 1) returns the user 
color in its result argument. 


e By tag array: the first shader may obtain the tag array and uses mi_call_shader to carry out 
volume shading in the desired way. It sets the final result in its resu/t argument, and returns 
(miBoolean)2 to indicate that volume shading has been completed. mental ray will then not 
call the remaining shaders in the list for the current ray segment. 


e By state: all mixed volume shaders called for a given ray segment are supplied the same state 
which can be used to exchange information, for example using state — user. This method 
is not recommended because it assumes that all shaders were designed to cooperate in this 
way. 


In any case, all volume shaders called for the volume will operate on the same result pointer. 


Sometimes, not all volumes through which a ray is traveling will contribute significantly to the 
final result. Consider a bubble of carbon dioxide inside a glass of beer. As the ray passes through 
the bubble, both shaders, CO2 and beer, will be called (since the bubble is inside the beer), but 
the beer is not going to contribute to the current ray since the bubble is completely filled with 


COz2. 


Here is an example with two volume shaders. The attenuating_volume volume shader at level 1 
which attenuates a ray according to the distance it has traveled through the volume. If two such 
volumes intersect, the effect is accumulating. see how the user color is used for that purpose. 
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The luminescent_volume volume shader at level 2 brightens the current ray. The effect is non- 
accumulating, so the shader return (miBoolean)2 to prevent mental ray from continuing to follow 


the shader list. 


struct lv { 


miScalar emission; 
miColor color; 
is 
DLLEXPORT miBoolean luminescent_volume ( 
miColor *result, 
miState *state, 
struct lv *parms ) 
{ 
miScalar factor; 
miColor *volcolor; 
factor = *mi_eval_scalar(&parms->emission) * state->dist; 
volcolor = mi_eval_color (&parms->color) ; 
result->r += factor * volcolor->r; 
result->g += factor * volcolor->g; 
result->b += factor * volcolor->b; 
return((miBoolean) 2) ; /* no more calls in chain */ 
} 


struct av { 


miScalar extinction; 
miColor color: 

+ 

DLLEXPORT miBoolean attenuating_volume( 
miColor *result, 
miState *state, 
struct av *parms ) 

{ 
miScalar tector: 
miColor *volcolor, *usercolor; 
factor = *mi_eval_scalar(&parms->extinction) * state->dist; 
volcolor = mi_eval_color (&parms->color) ; 
userColor = mi_volume_user_color(state) ; 
if (mi_volume_cur_shader(state) == 0) { 


usercolor->r = result->r - 

usercolor->g = result->g - 

usercolor->b = result->b - 
+} else { 


factor*volcolor->r; 
factor*volcolor->g; 
factor*volcolor->b; 


usercolor->r -= factor * volcolor->r; 
usercolor->g -= factor * volcolor->g; 


usercolor->b - 


factor * volcolor->b; 
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} 

if (mi_volume_cur_shader(state) == mi_volume_num_shaders(state)-1) 
*result = *usercolor; 

return (miTRUE) ; 


3.12 Environment Shaders 


Environment shaders provide a color for rays that leave the scene entirely, and for rays that would 
exceed the trace depth limit. Environment shaders are called automatically by mental ray if a ray 
leaves the scene, or when a ray exceeds the trace depth. It can also be done explicitly by shaders 
using the mi_trace_environment function: 


mi_reflection_dir(&dir, state); 
if (/* do ray tracing? */) 
mi_trace_reflection (&color, state, &dir); 
else 
mi_trace_environment(&color, state, &dir); 
/* use the returned color */ 


Environment shaders, like any other shader, may return miFALSE to inform the caller that the 
environment lookup failed. If mental ray falls back on calling the environment shader, it returns 
the value returned by the environment shader, not necessarily miFALSE. 


In both the explicit case and the automatic case (when a ray cast by a function call such as 
mi_trace-_reflection leaves the scene without intersecting with any object) mental ray calls the 
environment shader found in state—environment. In primary rays, this variable is initialized 
with the global environment shader in the camera (also found in state—camera—environment). 
Subsequent material shaders get the environment defined in the material if present, or the camera 
environment otherwise. 


In mental ray 2.x, material shaders never inherit the environment from the parent shader, they 
always use the environment in the material or the camera. All other types of shaders inherit the 
environment from the parent shader. In mental ray 3.x, the environment shader is inherited unless 
the material defines its own. 


Here is an example environment shader that uses a texture that covers an infinite sphere around 
the scene: 


struct mib_texture_lookup_spherical { 


miVector De ag 
miScalar rotate; 
miTag tex; 


ie 
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DLLEXPORT miBoolean mib_lookup_spherical ( 


miColor *result, 
miState *State, 
struct mib_texture_lookup_spherical *paras) 
‘ 
miTag tex = *mi_eval_tag(&paras->tex) ; 
miVector dir = *mi_eval_vector(&paras->dir) ; 
double theta, norm; 
result->r = result->g = result->b = result->a = 0; 
if (!tex) 
return (miFALSE) ; 
if (dir.x == 0 && dir.y == 0 && dir.z == 0) 
mi_vector_to_world(state, &dir, &state->dir) ; 
norm = mi_vector_norm(&dir) ; 
if (!norm) 
return (miFALSE) ; 
/* 
* without rotation, O is in the direction of the x axis, 
* increasing in a clockwise direction 
* / 
/* avoid calling atan2(0, 0), which return NaN on some platforms */ 
if (!dir.x && !dir.z) 
theta = 0.0; 
else 
theta = -atan2(dir.x, dir.z) / (2.0*M_PI); 
theta += *mi_eval_scalar(&paras->rotate) / M_PI; 
theta -= floor(theta) ; 
dir.x = theta; 
dir.y = asin(dir.y/norm) / M_PI + 0.5; 
dir.z = 0.0; 
return(mi_lookup_color_texture(result, state, tex, &dir)); 
} 


This shader uses a parameter in its shader parameter structure, a tag tex, to specify a texture 
shader. The texture is evaluated by calling milookup-_color_texture, which stores storing the 
texture coordinate in state—tex and calls the texture shader. For a description of texture shaders 
and how to call them, see the texture shader section on page 245. 


Here 1s an interesting variation of environment shaders that pastes the environment textures as a 
background plate, such that it exactly covers the rendered image plane. There are also parameters 
for zooming and panning to permit a bigger environment, if environment rays are cast outside 
the normal range. 
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struct mib_lookup_background { 
miVector Zoom; 
miVector pan; 
miBoolean torus_u; 
miBoolean torus_v; 
mitag tex; 


}; 


DLLEXPORT miBoolean mib_lookup_background ( 
miColor *result, 
miState *state, 
struct mib_lookup_background *paras) 


miVector *ZOOM; 

miVector *pan ; 

miVector coord; 

miTag tex = *mi_eval_tag(&paras->tex) ; 


if (!Itex) { 
result->r = result->g = result->b = result->a = 0; 
return (miFALSE) ; 
} 
zoom = mi_eval_vector(&paras->zoom) ; 
pan = mi_eval_vector(&paras->pan) ; 
coord.x = state->raster_x / state->camera->x_resolution * .9999; 
coord.y = state->raster_y / state->camera->y_resolution * .9999; 
coord.z = QO; 
coord.x = pan->x + (zoom->x ? zoom->x * coord.x : coord.x); 
coord.y = pan->y + (zoom->y ? zoom->y * coord.y : coord.y); 
if (*mi_eval_boolean(&paras->torus_u) ) 
coord.x -= floor(coord.x); 
if (*mi_eval_boolean(&paras->torus_v) ) 
coord.x -= floor(coord.y) ; 
if (coord.x < 0 || coord.y < 0 || coord.x >= 1 || coord.y >= 1) { 
result->r = result->g = result->b = result->a = 0 
return(miTRUE) ; 
} else 
return(mi_lookup_color_texture(result, state, tex, &coord)); 


Note that this shader returns miTRUE even if the ray missed the environment texture. Effectively, 
the shader considers all possible rays, and returns black if the texture is missed. If an environment 
does not cover all possible points around the scene, it should return black or some other valid 
color. 


3.13. Light Shaders 


Light shaders are called from other shaders by sampling a light using the mi_sample_light or mi_ 
trace_light functions, which perform some calculations and then call the given light shader, or 
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directly if a ray hits a source. mi_sample_light may also request that it is called more than once if 
an area light source is to be sampled. For an example for using mi_sample_light, see the section on 
material shaders above. mi_trace_light performs less exact shading for area lights, and is provided 
for backwards compatibility only. 


The light shader computes the amount of light contributed by the light source to a previous 
intersection point, stored in state—point. The calculation may be based on the direction state—dir 
to that point, and the distance state—dist from the light source to that ray. There may also be 
shader parameters that specify directional and distance attenuation. Directional lights have no 
location; state—-dist is undefined in this case. 


Light shaders are also responsible for shadow casting. Shadows are computed by finding all 
objects that are in the path of the light from the light source to the illuminated intersection 
point. This is done in the light shader by casting “shadow rays” after the standard light color 
computation including attenuation is finished. Shadow rays are cast from the light source back 
towards the illuminated point (or vice versa if shadow segment mode is enabled), in the same 
direction of the light ray. Every time an occluding object is found, that object’s shadow shader 
is called, if it has one, which reduces the amount of light based on the object’s transparency and 
color. If an occluding object is found that has no shadow shader, it is assumed to be opaque, so 
no light from the light source can reach the illuminated point. For details on shadow shaders, see 
the next section. 


Here is an example for a simple point light that supports no attenuation, but casts shadows: 


struct mypoint { 


miColor color: 
}; 
miBoolean mypoint ( 
register miColor *result, 
register miState *state, 
register struct mypoint *paras) 
4. 
*xresult = *mi_eval_color(&paras->color) ; 
return(mi_trace_shadow(result, state)) ; 
} 


The shader parameters are assumed to contain the light color. The shadows are calculated simply 
by giving the shadow shaders of all occluding objects the chance to reduce the light from the 
light source by calling mi_trace_shadow. The shader returns miTRUE if some light reaches the 
illuminated point. 


There is a useful trick that can improve performance significantly: the light shader should trace 
shadow rays only if the contribution from the light is greater than some threshold, for example 
because distance or angle attenuation has left so little of the light color (less than 1/256, for 
example) that it does not matter whether this contribution is counted or not. If this is the case, 
the shader might skip shadow calculation (significantly increasing speed in a complex scene) and 
return (miBoolean)2 to indicate that if this is a small area light source, there is no point in 
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continuing to sample it because all the other samples are not going to make a contribution either. 
Returning 2 does not work well for large area light sources because some parts of the light may 
be closer than others and may exceed the threshold for returning early. Consider the following 
alternate shader body: 


: 
*result = *mi_eval_color(&paras->color) ; 
apply_distance_attenuation(result) ; 
apply_angle_attenuation(result) ; 
if (result->r < .005 && result->g < .005 
&& result->b < .005) 
return ((miBoolean) 2) ; 
else 
return(mi_trace_shadow(result, state)); 
} 


The point light can be turned into a spot light by adding directional attenuation parameters for 
the inner and outer cones and a spot direction parameter to the shader parameters, and change 
the shader to reduce the light intensity if the illuminated point falls between the inner and outer 
cones, and turns the light off if it does not fall into the outer cone at all: 


struct mib_light_spot { 


miColor color; /* color of light source */ 
miBoolean shadow; /* light casts shadows */ 
miScalar factor; /* makes opaque objects transparent */ 
miBoolean atten; /* distance attenuation */ 
miScalar Start, stop; /* if atten, distance range */ 
miScalar cone; /* inner solid cone */ 

I; 

DLLEXPORT miBoolean mib_light_spot ( 
register miColor *xresult, 
register miState *state, 
register struct mib_light_spot *paras) 

{ 
register miScalar d, t, start, stop, cone; 
miScalar spread; 
miVector Lair, air? 
miTag ltag; 


*result = *mi_eval_color(&paras->color) ; 
if (state->type != miRAY_LIGHT) /* visible area light*/ 
return (miTRUE) ; 

/*xangle atten*/ 
ltag = ((miInstance *)mi_db_access(state->light_instance) )->item; 
mi_db_unpin(state->light_instance) ; 
mi_query(miQ_LIGHT_DIRECTION, state, ltag, &ldir); 
mi_vector_to_light(state, &dir, &state->dir) ; 
mi_vector_normalize(&dir) ; 

d = mi_vector_dot(&dir, &ldir); 
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if (d <= 0) 
return (miFALSE) ; 
mi_query(miQ_LIGHT_SPREAD, state, ltag, &spread); 
if (d < spread) 
return (miFALSE) ; 
cone = *mi_eval_scalar(&paras->cone) ; 
if (d < cone) f{ 
t = 1 - (d - cone) / (spread - cone); 
result->r *= t; 
result->g *= t; 
result->b *= t; 


, 
if (*mi_eval_scalar(&paras->atten)) { /* dist atten*/ 
stop = *mi_eval_scalar(&paras->stop) ; 
if (state->dist >= stop) 
return (miFALSE) ; 
start = *mi_eval_scalar(&paras->start) ; 
if (state->dist > start && fabs(stop - start) > EPS) { 
t = 1 - (state->dist - start) / (stop - start); 
result->r *= t; 
result->g *= t; 
result->b *= t; 
} 
} 
if (*mi_eval_boolean(&paras->shadow)) { /* shadows: */ 
d = *mi_eval_scalar(&paras->factor) ; 
if (d <1) { 
miColor filter; 
filter.r = filter.g = filter.b = filter.a = 1; 
/* opaque */ 
if (!mi_trace_shadow(&filter,state) || BLACK(filter)) { 
result->r *= d; 
result->g *= d; 
result->b *= d; 
if (d == 0) 
return (miFALSE) ; 
} else { /* transparent*/ 
double omf = i - d; 
result->r *= d+ omf * filter.r; 
result->g *= d+ omf * filter.g; 
result->b *= d+ omf * filter.b; 
} 
} 
+ 
return (miTRUE) ; 


This shader performs both distance attenuation (it illuminates only between the start and stop 
parameters if defined) and angle attenuation (full energy up to cone, then a linear falloff to the 
spread of the light source definition, accessed with mi_query). Outside spread the shader will 
not even get called (this is why spread is a light definition parameter, not a shader parameter — 
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mental ray needs it reject light sources during sampling). The shader can also handle visible light 
sources: it returns its light color if the ray type is not equal to miRAY_LIGHT. Finally, the shader 
casts shadow rays if they are enabled to reduce the returned light if there are occluding objects. 


Note that none of these light shaders takes the normal at the illuminated point into account; the 
light shader is merely responsible for calculating the amount of light that reaches that point. The 
material shader (or other shader) that sampled the light must use the dot_nd value returned by 
mi_sample_light, and its own shader parameters such as the diffuse color, to calculate the actual 
fraction of light reflected by the material. Note also that state — instance is not the instance of 
the light but of the illuminated point; use state — light_instance instead. 


mental ray 3.1 also supports geometric area light sources, which behave like the fixed four area 
light source types (rectangle, disc, sphere, and cylinder) except that the light shape is defined by 
an object instance. All points on the surface of the object are emitting light uniformly. For every 
light sample, mental ray constructs an intersection point with the object, and then calls the light 
shader. The light shader now has two sets of parameters: 


e The state contains the same values as for any other light shader. In particular, state — point 
and the other intersection-related state variables describe the illuminated point. 


e The state — child state contains the intersection information for the light object, just like 
a material shader would receive it, including texture coordinates if available. For example, 
state — child — point contains the chosen light-emitting intersection point on the light 
object. Note that the child state’s local space is the object’s internal space, not the light’s 
internal space; it is recommended that the instance that connects the light and the light 
object uses an identity transformation. 


If the light object is uniformly emitting light from all points on its surface, no modifications to 
the light shader are required to work with geometric area light sources. Note that geometric area 
light source are supported only for point lights, but not spot or infinite lights. 


mental ray 3.1 and higher support an additional user-defined area light source, which leaves 
sample point selection to the light shader. The light shader is expected to select points on its 
surtace, cast shadow rays at these points if required, and return the illumination from that point. 
mental ray treats such lights as zero-dimension point lights, and puts the light position into 
state — org. The light shader modifies this value as necessary. The shader is called repeatedly 
until it returns (miBoolean) 2. A call counter is provided in state — count, which is 0 for the first 
call, and counts up to 65536 (normally a few or a few tens of calls are considered sufficient). 


mental ray 3.1 also supports light profiles, such as IES or Eulumdat light profiles, that are supplied 
by physical lamp vendors. This requires a special light shader that attenuates its light color (which 
is not provided by the profile) by the profile’s directional attenuation specification. This is done 
by the milightprofile_sample*:' shader interface function, which requires a profile argument that 
is taken from a shader parameter: 


typedef struct { 
miColor color; /* color of light source */ 
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miTag profile; /* tag of ies profile to use */ 
} photometric_light_t; 


DLLEXPORT int photometric_light_version(void) f{return(1) ;} 


DLLEXPORT miBoolean photometric_light ( 


miColor *result, 
miState *State, 
photometric_light_t *paras) 

{ 
miTag lp_tag = *mi_eval_tag(&paras->profile) ; 
miScalar factor = mi_lightprofile_sample(state, lp_tag, miTRUE) ; 
factor *= 1.0 / (state->dist * state->dist) ; 
*result = *mi_eval_color(&paras->color) ; 
result->r *= factor; 
result->g *= factor; 
result->b *= factor; 
return(mi_trace_shadow(result, state)); 

: 


This shader performs physically correct inverse-square distance falloff, and also takes care of 
shadows. Here is a scene example that uses this shader: 


declare shader 
color "photometric_light" ( 
color "EGiat s 
lightprofile "profile") 
version 1 
end declare 


lightprofile "myprof" 

format ies 

hermite 1 

file "/usr/local/ies/profile.ies" 
end lightprofile 


light "mylight" 
"photometric_light" ( 
“cOoLor* 100 100 100, 
"profile" "myprof") 


end light 
The light color is chosen large because of the inverse-square falloff; it depends on the distance 


from the light to the illuminated point. This scene fragment assumes that an IES light profile file, 
as provided by the lamp vendor, exists in /usr/local/ies/profile.ies. 
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3.14 Shadow Shaders 


As described in the previous section, light shaders may trace shadow rays between the light source 
and the point to be illuminated. When this ray hits an occluding object, that object’s shadow shader 
is called, if present. (If the object has no shadow shader, the object is assumed to block all light.) 
Shadow shaders accept an input color that is dimmed according to the transparency and color 
of the occluding object. If the resulting color is black, that is, if the object is fully opaque, the 
shadow shader should return miFALSE. 


If there is more than one occluding object between the light source and the illuminated point, 
the order in which the shadow shaders of the occluding objects are called is undefined, unless 
shadow sorting or segmented shadows are turned on. Shadow shaders that rely on being called 
in the correct order, the one closest to the light source first, should define shadow sort in their 
shader declaration to ensure that shadow sorting is enabled if the shader is used. 


Shadow shaders should check for shadow segment mode. If shadow segments are turned on, 
shadow shaders must behave rather differently, similar to computing transparency in material 
shaders. The shadow ray points from the previous intersection (or the illumination point for the 
initial segment) to the current intersection point. It should set up state — refraction_volume for 
the next shadow segment, obtain the illumination by calling mi_trace_shadow-seg, and then apply 
the usual modifications. 


Shadow shaders should distinguish two cases: 


e state — options — shadow is 1 or ’1? 
All shadow ray origins are at the light source, and their intersection point is on the 
intersection object whose shadow shader was called. The mi_trace_shadow call by the 


light shader calls all shadow shaders. 


e state — options — shadow is ’s’ 
Shadow rays travel in the opposite direction and form a chain from the illuminated point 
towards the light source. Each shadow ray’s origin is the previous ray’s end point. The 
shadow shader must perform inside/outside calculations and leave the correct volume 
shader in state — volume. The mi_trace_shadow call by the light shader only calls the first 
shadow shader closest to the illuminated point; that shadow shader must call mi-_trace- 
shadow-seg after choosing the volume. 


If a new material shader is written, it is often necessary to also write a matching shadow shader. 
The shadow shader performs a subset of the calculations done in the material shader: it may 
evaluate textures and transparencies, but it will not sample lights and it will not cast secondary 
rays (other than shadow rays in shadow segment mode). The shader writer can either write a 
separate shadow shader, or let the material shader double as shadow shader by building the scene 
such that the material shader appears twice in the material definition. Most shaders take the latter 
approach. It relies on the material shader to omit all calculations that are necessary only in the 
material shader when called as a shadow shader. The shader can find out whether it is called as a 


material shader or as a shadow shader by checking if state—type is miRAY_SHADOW: if yes, this is a 
shadow shader. 
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The following shadow shader is a separate shader that attenuates the light that passes through the 
object based on two shader parameters, the diffuse color and the transparency. Material shaders 
usually also have ambient and specular colors, but the best approach is to pass the diffuse color 
to shadow shaders because it describes the “true color” of the object best. Note that the scene 
can be arranged such that although the shadow shader is separate from the material shader, it 
still gets a copy of the material shader’s shader parameters so the shadow shader can access the 
“true” material parameters. In a .mi file, this is done by declaring the shadow shader with no 
parameters and naming none in the shadow statement in the material definition (just give (). 
This sharing of parameters even if the shader itself is not shared avoids having to duplicate a large 
set of parameters. 


miBoolean myshadow( 


miColor *result, 
miState *xstate, 
struct myshadow *paras) 
{ 
miScalar opacity; 
miScalar f, omf; 
if (state->options->shadow == ’s’) { 
set up state->refraction_volume; 
if (!mi_trace_shadow_seg(result, state)) 
result->r = result->g = result->b = 0; 
t 
opacity = 1 - *mi_eval_scalar(&paras->transp) ; 
if (opacity < 0.5) { 
f = 2 * opacity; 
result->r *= f * diffuse.r; 
result->g *= f * diffuse.g; 
result->b *= f * diffuse.b; 
} else { 
f= 2 * (opacity - 0.5); 
omit = 1=- f£:; 
result->r *= £ + omf * diffuse.r; 
result->g *= f + omf * diffuse.g; 
result->b *= f + omf * diffuse.b; 
t 
return(result->r != 0 || result->g != 0 || result->b != 0); 
} 


In non-segmented shadow mode, the org variable in the state always contains the position of the 
light source responsible for casting the shadow rays. The point state variable contains the point 
on the shadow-casting object. The dist state variable is the distance to the light source (except 
for directional lights, which have no origin). In shadow segment mode, shadow rays travel in 
the opposite direction; org is the previous intersection (or the illumination point for the initial 
segment), and dir points towards the light source. 


266 3 Using and Writing Shaders 


3.15 Photon Shaders 


Photon shaders are used in the photon tracing phase to compute the photon maps that are used 
to simulate caustics and global illumination. Like shadow shaders, they are specified in materials, 
and can share the material shader’s parameters, or its implementation. Photon shaders need 
to use the mi_photon_reflection_* and mi_photon_transmission.* functions to reflect or transmit 
photons. They can also, if desired, use the built-in functions to generate new photon directions: 
mi_reflection_dir_* and mi_transmission_dir_*. 


The following is a simple photon shader example that handles the interaction between a photon 
and a simple transmitting material. Notice how the incoming energy is modified before the new 
photon is transmitted; this is according with the fact that photons move in the opposite direction 
of the rays in the raytracing phase. 


struct ptparm { 
miScalar trans; /* fraction of light transmitted */ 


miScalar ior; /* index of refraction */ 
}; 
miBoolean ptrans_photon( 
miColor *result, 
miState *state, 
struct ptparm  *paras) 
{ 
miVector dir; 
miColor new_energy ; 
miScalar trans; 
mi_refraction_dir(&dir, state, 1.0, 
*mi_eval_scalar(&paras->ior)) ; 
trans = *mi_eval_scalar(&paras->trans) ; 
new_energy.r = result->r * trans; 
new_energy.g = result->g * trans; 
new_energy.b = result->b * trans; 
mi_photon_transmission_specular(&new_energy, state, &dir); 
return (miTRUE) ; 
} 


This photon shader only handles transmission and it only generates one photon. It is 
recommended to produce only one photon in a photon shader. If the photon shader supports 
several types of reflection or transmission, it should use mi_choose_scatter_type to select only one 
of these per photon interaction such that only one photon is propagated. If several photons are 
generated in a photon shader, the number of photons in the photon map might grow very quickly 
without obtaining the necessary quality. 


Incoming photons should be stored on materials with a diffuse surface. This is done in the photon 
shader by calling m_store_photon. 
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To benefit from the photon maps (consisting of the photons stored by the photon shaders), 
the material shaders should include the illumination from the photon maps using mi_compute- 
irradiance. This is illustrated in the following example of a simple diffuse surface simulated using 
a material shader and its corresponding photon shader. 


pdif photon isa simple example of a photon shader that stores a photon; pdif is material shader that 
displays the photon map. Since the pdif_photon shader only computes caustics, it does not reflect 
the photon off the diffuse surface. The pdif material shader does not compute direct illumination 
from the light sources and only takes the caustic into account. 


struct pdparm { 
miColor diffuse; 


i? 

miBoolean pdif_photon( 
miColor *result, 
miState *state, 
struct pdparm *paras) 

{ 
mi_store_photon(result, state) ; 
return (miTRUE) ; 

i; 


int pdif_version(void) {return(1) ;} 


miBoolean pdif ( 


miColor *result, 
miState | *State, 
struct pdparm *paras ) 

| 
miColor irrad, *diffuse; 
mi_compute_irradiance(&irrad, state) ; 
diffuse = mi_eval_color(&paras->diffuse) ; 
result->r = irrad.r * diffuse->r; 
result->g = irrad.g * diffuse->g; 
result->b = irrad.b * diffuse->b; 
result->a = 1.0; 
return (miTRUE) ; 

; 


In a scene consisting of a glass lens that creates a caustic on a ground plane, four shaders need to 
be attached: 


e The material of the glass object references a refractive material shader (not described here). 
e The material of the glass object references ptrans_photon as photon shader. 


e The material of the ground plane object references pdif as material shader. 
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e The material of the ground plane object references pdif_photon as photon shader. 


Here is a more complete example of a photon shader. It simulates diffuse, glossy, and specular 
reflection, and can be used for both caustics (both caustic generation and receiving) and global 
illumination. 


miBoolean dgs_material_photon( 


miColor *energy, 
miState *state, 
struct dgs_material *paras) 
{ 
struct dgs_material m; 
miColor color; 
miVector dir: 
miScalar LOr in, 266 0uGs 
miRay_type type; 
miBoolean ok; 
/* 


* Make a local copy of the parameters (light 
* sources are not used here) 


* / 
m.diffuse = *mi_eval_color (&paras->diffuse) ; 
m.glossy = *mi_eval_color (&paras->glossy) ; 
m.specular = *mi_eval_color (&paras->specular) ; 
m.shiny = *mi_eval_scalar(&paras->shiny) ; 
m.shiny_u = *mi_eval_scalar(&paras->shiny_u) ; 
m.shiny_v = *mi_eval_scalar(&paras->shiny_v) ; 
m.transp = *mi_eval_scalar(&paras->transp) ; 
m.ior = *mi_eval_scalar(&paras->ior) ; 
/* 


* Insert photon in map if this is a diffuse 
* surface. 


* / 


if (m.diffuse.r > miEPS || 
m.diffuse.g > miEPS || 
m.diffuse.b > miEPS) 
mi_store_photon(energy, state); 


/* 
* Choose scatter type for new photon 


* / 


type = mi_choose_scatter_type(state, m.transp, 
&m.diffuse, 
&m.glossy, 
&m. specular) ; 


/* 
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* %* *€ * 


* / 


Shoot new photon: Compute new photon color 
(compensating for Russian roulette) and shoot 
new photon in a direction determined by the 
scattering type 


switch (type) { 


/* no reflection. or transmission */ 


case miPHOTON_ABSORB: 


case m 


return (miTRUE) ; 


/* specular reflection (mirror) */ 
iPHOTON_REFLECT_SPECULAR: 
color.r = energy->r * m.specular.r; 
color.g = energy->g * m.specular.g; 
color.b = energy->b * m.specular.b; 
mi_reflection_dir_specular(&dir, state); 
return mi_photon_reflection_specular(&color, state, &dir); 


/* glossy reflection (Ward model) */ 


case miPHOTON_REFLECT_GLOSSY: 


color.r = energy->r * m.glossy.r; 
color.g = energy->g * m.glossy.g; 
color.b = energy->b * m.glossy.b; 
if (m.shiny) 
/* isotropic glossy reflection */ 
mi_reflection_dir_glossy(&dir, state, m.shiny) ; 
else { /* anisotropic glossy reflection */ 
miVector u, V; 
miASSERT(m.shiny_u > 0 && m.shiny_v > 0); 
anis_orientation(ku, &v, state); 
mi_reflection_dir_anisglossy(&dir, state, 
&u, &v, m.shiny_u, m.shiny_v); 
t 


return(mi_photon_reflection_glossy(&color, state, &dir)); 


/* diffuse (Lamberts cosine law) */ 


case miPHOTON_REFLECT_DIFFUSE: 


color.r = energy->r * m.diffuse.r; 

color.g = energy->g * m.diffuse.g; 

color.b = energy->b * m.diffuse.b; 
mi_reflection_dir_diffuse(&dir, state); 
return(mi_photon_reflection_diffuse(&color, state, &dir)); 


/* specular transmission */ 


case miPHOTON_TRANSMIT_SPECULAR: 


color.r = energy->r * m.specular.r; 

color.g = energy->g * m.specular.g; 

color.b = energy->b * m.specular.b; 
refraction_index(state, &m, &ior_in, kior_out) ; 
miASSERT(ior_in >= 1 && ior_out >= 1); 


return(ior_out == ior_in 
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? mi_photon_transparent(&color, state) 

: mi_transmission_dir_specular(&dir, state,ior_in,ior_out) 
? mi_photon_transmission_specular(&color, state, &dir) 

: miFALSE) ; 


/* glossy transmiss. (Ward model) */ 
case miPHOTON_TRANSMIT_GLOSSY: 
color.r = energy->r * m.glossy.r; 
color.g = energy->g * m.glossy.g; 
color.b = energy->b * m.glossy.b; 
refraction_index(state, &m, &ior_in, &ior_out); 
miASSERT(ior_in >= 1 && ior_out >= 1); 


if (m.shiny) /* isotropic glossy transmission */ 
ok = mi_transmission_dir_glossy(&dir, 
state, ior_in, ior_out, m.shiny) ; 
else { /* anisotropic glossy transmission */ 
miVector u, Vv; 
miASSERT(m.shiny_u > 0 && m.shiny_v > 0); 
anis_orientation(ku, &v, state); 
ok = mi_transmission_dir_anisglossy(kdir, state, 
ior_in, ior_out, &u, &v, m.shiny_u, m.shiny_v); 
} 
if (ok) 
return(ok ? mi_photon_transmission_glossy(&color, state, &dir) 
: miFALSE) ; 


/* diffuse transm. (translucency) */ 
case miPHOTON_TRANSMIT_DIFFUSE: 
color.r = energy->r * m.diffuse.r; 
color.g = energy->g * m.diffuse.g; 
color.b = energy->b * m.diffuse.b; 
mi_transmission_dir_diffuse(&dir, state); 
return(mi_photon_transmission_diffuse(&color, state, &dir)); 


default: /* Unknown scatter type */ 
mi_error("unknown scatter type in dgs photon shader") ; 
return (miFALSE) ; 


The first thing that happens in dgs_material_photon is that the reflection parameters are evaluated 
with mi_eval_*. Then the photon is stored if the surface is diffuse and the photon is not 
directly from the light source. Second, the function mi_choose-_scatter_type is called. Based 
on the transparency and reflection coefficients, it decides whether the photon should be 
absorbed, reflected diffusely, glossily, or specularly, or refracted diffusely, glossily, or specularly. If 
absorption is not chosen, m1_choose_scatter_type changes the reflection coefficients of the chosen 
reflection or refraction type to compensate for the fact that the photon “survived”. This is a 
method known as “Russian Roulette”. 
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If the photon is absorbed, dgs_material_photon simply returns at this point. If the photon should 
be reflected or refracted, the energy of the new photon is computed, a new direction is computed 
(using the built-in functions to compute reflection and refraction directions), and the photon is 
emitted in that direction. 


Instead of using Russian Roulette to determine whether the photon should be absorbed or not, 
one could also emit a new photon for each type of reflection and refraction that has a non- 
zero reflection coefficient. Each emitted photon should have an energy that is the energy of the 
incoming photon multiplied by the reflection coefficient for that reflection (or refraction) type. 
However, this means that each photon emitted from the light source can cause many photons to 
be stored, some with very insignificant energy. The advantage of using Russian Roulette is that 
all the stored photons have comparable energies — no storage is wasted saving photons with low 
energy. 


Obviously scene creation is simplified if the material shaders are written such that they also 
function as photon shaders, and also as shadow shaders, because the same shader can be attached 
to the respective materials three times, as material shader, photon shader, and shadow shader. If 
no parameters are specified for the photon and shadow shader references, mental ray will pass 
the material shader arguments to them, so they need not be duplicated twice. A shader can find 
the context in which it is called by examining state — type. 


3.16 Photon Emitter Shaders 


Photon emitter shaders are used in the photon tracing phase to control the emission of photons 
from the light sources. There exists a number of built-in photon emitters that handle the following 
types of light sources: 


e Point lights: emit photons with equal flux in all directions around the point light. 


e Spot lights: emit photons with equal flux within the cone specified by the spotlight 
parameters. 


e Directional lights: emit photons with equal radiance (based on the energy). Since a 
directional light source is strictly non-physical, the energy concepts are different from 
the other light sources. 


e Disc area lights: emit photons from different points on the disc in directions based on a 
cosine distribution. 


e Rectangle area lights: emit photons from different points on the rectangle in directions 
based on a cosine distribution. 


e Sphere area lights: emit photons with equal flux from the surface of the sphere based on an 
equal distribution at each surface point. 


e Cylinder area lights: emit photons with equal flux from the surface of the cylinder based 
on an equal distribution. No photons are emitted from the two disc-shaped “ends” of the 
cylinder. 
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Unless there are good reasons, these light sources should be used since they are well optimized. 
This is particularly true for the point light and sphere light which use a projection map to limit 
the emission of photons to the directions in which caustics generating objects are found. The 
appropriate built-in photon emitters are automatically applied if no photon emitter is specified 
in the light source definition. 


If more complex light sources are needed, it can be necessary to write a specialized shader. For 
example, this could be necessary for a spot light that should support intensity fading near the 
edges of the cone. Note that the light emitter shader is not called if the light has zero energy; such 
lights are ignored by mental ray during photon tracing. 


An example of a simple point light that emits photons uniformly in all directions around the 


current point is given in the following shader’. The shader receives information about the light 
source from state — light_instance. 


void point_emitter_init ( 


miState *state, 
void *D, 
miBoolean *xinst_init_req) 
{ 
miTag light_tag; 
miMatrix *T ; 
if (!p) 
*inst_init_req = miTRUE; 
else { 
miVector org, *torg, **user; 
torg = mi_mem_allocate(sizeof (miVector)) ; 
mi_query(miQ_INST_ITEM, state, 
state->light_instance, &light_tag) ; 
mi_query (miQ_INST_LOCAL_TO_GLOBAL, state, 
state->light_instance, &T); 
mi_query(miQ_LIGHT_ORIGIN, state, 
light_tag, korg); 
mi_point_transform(torg, korg, *T); 
mi_query(miQ_FUNC_USERPTR, state, 0, kuser); 
*xuser = torg; 
} 
; 
void point_emitter_exit ( 
miState *state, 
void *p) 
{ 
miVector **USEL ; 


mi_query(miQ_FUNC_USERPTR, state, 0, &user); 


>This is just a simple example shader — the built-in point light emitter is much more efficient. 
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if (*user && p) { 
mi_mem_release(*user) ; 
*user = NULL; 


} 

} 

miBoolean point_emitter ( 
miColor *energy, 
miState *state, 
void *p) 

{ 
miVector *KUSEL ; 
mi_query(miQ_FUNC_USERPTR, state, 0, &user); 
state->org = *(miVector *)*user; 
mi_scattering_dir_diffuse(&state->dir, state); 
mi_photon_light (energy, state); 
return (miTRUE) ; 

} 


This shader does not have any parameters. Instead it extracts all information about the light source 
with mi_query. This shader can be attached to a light definition using the photon statement. Note 
the choice of direction using mi_scattering_dir_diffuse, which is called to set the (normalized) 
photon direction. The org and dir or any other ray state variables are undefined when the shader 
is called, the shader must come up with its own directions. 


If a photon emitter shader returns miFALSE, photon emission from the current light source is 
aborted at that point and no more photons are cast from this light source. It is recommended 
that photon emitter shaders return miTRUE only if they called mi_photon_light because otherwise 
mental ray will keep calling the shader for a long time without ever storing a photon. 


Here is a more elaborate example that implements a spherical light emitter. It should be attached 
to a spherical area light source. The shader uses the radius of the area light source as the radius of 
the sphere that emits the photons. Similarly, it uses the light origin as the center of the emission 
sphere, so the shader needs no parameters. It uses an init shader to compute constant data only 
once per frame instead of once per photon. 


struct ball_emitter_data { 


miVector org; 
miScalar radius; 
}; 
DLLEXPORT void ball_emitter_init ( 
miState *State, 
void *D, 
miBoolean *inst_init_req) 
4 
miTag light_tag; 
miMatrix *T ; 


miVector org; 
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struct ball_emitter_data **user, *data; 


if ('p) { 
*inst_init_req = miTRUE; 
return; 

i 


mi_query(miQ_FUNC_USERPTR, state, 0, user); 
data = *user = mi_mem_allocate(sizeof (struct ball_emitter_data)) ; 


mi_query(miQ_INST_ITEM, state, state->light_instance, &light_tag) ; 
mi_query(miQ_INST_LOCAL_TO_GLOBAL, state, state->light_instance, &T); 
mi_query(miQ_LIGHT_ORIGIN, state, light_tag, &org); 

mi_query (miQ_LIGHT_AREA_S_RADIUS, state, light_tag, &data->radius) ; 


mi_point_transform(&data->org, korg, *T); 


DLLEXPORT void ball_emitter_exit ( 


miSstate *state, 
void *p) 
if {p) 4 


struct ball_emitter_data **user; 


mi_query(miQ_FUNC_USERPTR, state, 0, &user); 
mi_mem_release(*user) ; 
*user = NULL; 


DLLEXPORT miBoolean ball_emitter( 


miColor *energy, 
miState *State, 
void *paras) /* not used, no parameters */ 


struct ball_emitter_data **user; 


double samples [3] ; 
miVector shiztt: 
miColor comp_energy ; 


mi_query(miQ_FUNC_USERPTR, state, 0, &user); 
state->org = (*user)->org; 


/* get single 3-dimensional sample */ 
mi_sample(samples, NULL, state, 3, NULL); 
shift.x = 2 * samples[0] - 1; 

shift.y = 2 * samples[1i] - 1; 

shift.z = 2 * samples[2] - 1; 


/* rejected sample */ 
if (mi_vector_norm(&shift) > 1.0) 
return (miTRUE) ; 
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mi_vector_mul(&shift, (*user)->radius) ; 
mi_vector_add(&state->org, &state->org, &shift) ; 


/* compensate photon energy by the proportion of rejected samples */ 
/* volume of cube / volume of ball = 8 / (4/3 PI) = 6 / PI */ 
comp_energy.r = energy->r * 6 / M_PI; 

comp_energy.g = energy->g * 6 / M_PI; 

comp_energy.b = energy->b * 6 / M_PI; 


mi_scattering_dir_diffuse(&state->dir, state); 


mi_photon_light (&comp_energy, state) ; 
return (miTRUE) ; 


Like light shaders, emitter shaders also support geometric area light sources. No special changes 
need to be made if all points on the light object emit light uniformly, but the emitter shader 
also has access to the chosen emission point on the light object in state — child. The state is the 
normal emission shader state, and the child state is similar to the state a material shader would 
find when a visible ray intersects the object. In particular, the point and tex_list state variables are 
set correctly in state — child. See page 262 for more detail. 


3.17. Lens Shaders 


Lens shaders are called for primary rays from the camera. The camera is normally a simple pinhole 
camera. A lens shader modifies the origin and direction of a primary ray from the camera. More 
than one lens shader may be attached to the camera; each modifies the origin and direction 
calculated by the previous one. By convention, all rays up to and including the one leaving the 
last lens are called “primary rays”. The origin and direction input parameters can be found in 
the state, in the origin and dir variables. The outgoing ray is cast with mi_trace_eye, whose return 
color may be modified before the shader itself returns. Lens shaders are called recursively; a call 
to mi_trace_eye will call the next lens shader if there is another one. 


Here is a sample lens shader that implements a fish-eye lens: 


miBoolean fisheye ( 


miColor *result, 
miState *state, 
void *paras ) 

| 
miVector camdir, dir; 
miScalar hs Ve Ey. TG 


mi_vector_to_camera(state, &camdir, &state->dir) ; 
t = state->camera->focal / -camdir.z / 
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(state->camera->aperture/2) ; 


xX = t * camdir.x; 

y = t * camdir.y * state->camera->aspect ; 
LHR e ar y SF YY; 

ni dae oe eae Oe 


dir.x = camdir.x * I; 

dir.y = camdir.y * r; 

dir.z = -sqrt(1 - dir.x*dir.x - dir.y*dir.y); 

mi_vector_from_camera(state, &dir, &dir); 

return(mi_trace_eye(result, state, &state->org, &dir)); 
+ else { 

result->r = result->g 

result->b = result->a 

return (miFALSE) ; 


0; 


This shader does not take the image aspect ratio into account, and is not physically correct. It 
merely bends rays away from the camera axis depending on their angle to the camera axis. Rays 
that fall outside the circle that touches the image edges are set to black (note that alpha is also 
set to 0). The rays are bent according to the square of the angle, which approaches the physically 
correct deflection for small values of 7. This example shader has no shader parameters, which is 
why the type of the paras parameter is void *. 


Be sure to derive the ray origin from state — org, not state — point, which is undefined in lens 
shaders and can cause incorrect and empty or extremely noisy pictures. 


3.18 State Shaders> 


State shaders are functions that are invoked to set up and clean up states, and before and after 
all forms of primary ray casting. mental ray usually uses the same state for a number of related 
shader calls, such as for all primary rays of a screen-space tile, which means that state shaders are 
typically called more often in sample than state mode. The mode is passed in the structure passed 
as the fourth argument. The following calls occur: 


e Rendering: 


o miSHADERSTATE_STATE_EXIT when a tile of the image finishes. 
o miSHADERSTATE_SAMPLE_INIT before each eye ray. 


o miSHADERSTATE_SAMPLE_EXIT after each eye ray, but before the result is stored in the 
frame buffers. 


o miSHADERSTATE_STATE_INIT when a tile of the image starts. 
e Displacement: 


o miSHADERSTATE_STATE_INIT for each displaced subobject. 
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o miSHADERSTATE_SAMPLE_INIT before each displacement shader call. 
o miSHADERSTATE_SAMPLE_EXIT directly after each displacement shader call. 
o miSHADERSTATE_STATE_EXIT after a subobject has been displaced. 


e Lightmapping: 
o miSHADERSTATE_STATE_INIT before the first vertex of each subobject. (Objects may 


be split into subobjects if they are too large.) 


o miSHADERSTATE_SAMPLE_INIT before each lightmap shader call, in either vertex or 
output mode. 


o miSHADERSTATE_SAMPLE_EXIT after each lightmap shader call, in either vertex or 
output mode. 


o miSHADERSTATE_STATE_EXIT after the lightmap shader has been called in output mode 

(ie. for the last time for this subobject). 
e Photons: 

o miSHADERSTATE_STATE_INIT before starting to cast a bundle of photons. A bundle 
has about 5000-10000 photons. 

o miSHADERSTATE_SAMPLE_INIT before a photon is cast. 

o miSHADERSTATE_SAMPLE_EXIT after a photon has been cast. 

o miSHADERSTATE_STATE_EXIT after finishing the bundle of photons. 


e Finalgather preprocessing before image rendering starts: 


o miSHADERSTATE_STATE_INIT before a set of finalgather points 1s set. 


o miSHADERSTATE_SAMPLE_INIT before each finalgather point is set. (Each point involves 
a large number of finalgather rays.) 


o miSHADERSTATE_SAMPLE_EXIT after each finalgather point is finished. 
o miSHADERSTATE_STATE_EXIT after the set of finalgather points is finished. 


e Geometry shader: 


miSHADERSTATE_STATE_INIT before each geometry shader call. 
o miSHADERSTATE_SAMPLE_INIT before each geometry shader call. 
miSHADERSTATE_SAMPLE_EXIT after each geometry shader call. 

o miSHADERSTATE_STATE_EXIT after each geometry shader call. 


O 


O 


e Output shader: 


o miSHADERSTATE_STATE_INIT before the first output shader is called. 
miSHADERSTATE_SAMPLE_INIT before each output shader call. 

o miSHADERSTATE_SAMPLE_EXIT after each output shader call. 
miSHADERSTATE_STATE_EXIT after the last output shader has been called. 


O 


O 
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The call statement in the .mi scene description language does not cause state shaders to be 
called. Note that sample exit shaders are called immediately after the associated shader call (lens, 
material, displacement, etc.), and receive the same result pointer as their first argument. This 
can be used to manipulate returned values, especially in cases like light mapping where no lens 
shaders are called. 


struct state_arg { 


int count ; 
float s; 

yi; 

miBoolean state_ext ( 
miColor *result, 
miState *state, 
struct state_arg *param, 
miShader_state_arg *arg) 

{ 
const char *key = "StateExtension"; 
miBoolean res = miFALSE; 


if (state->type != miRAY_EYE) { 

/* state shaders may be called in various situations, 
* here we only deal with actual rendering. */ 

return(miFALSE) ; 

} 

switch(arg->op) { 

case miSHADERSTATE_STATE_INIT: { 

MyStateExt myState; /* prepare state */ 


res = mi_shaderstate_set(state, key, &myState, 


sizeof (MyStateExt) , miSS_LIFETIME_RECT) ; 
} break; 


case miSHADERSTATE_STATE_EXIT: 
/* cleanup state */ 


res = mi_shaderstate_set(state, key, NULL, 0, miSS_LIFETIME_RECT) ; 
break; 


case miSHADERSTATE_SAMPLE_INIT: { 
/* do something before sampling starts */ 
MyStateExt *myState = mi_shaderstate_get(state, key, 0); 
res = miTRUE; 
} break; 


case miSHADERSTATE_SAMPLE_EXIT: 
if (arg->shader_return) { 
/* if sampling was successful, do something */ 
MyStateExt *myState = mi_shaderstate_get(state,key,0); 


“ee @ @ 


res = miTRUE; 
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} 
break; 


default: 
/* this should never happen, add error handling */ 


t 


return res; 


The declaration of a state shader looks just like a regular shader declaration: 


declare shader 
color state_ext ( 
integer "count", 
scalar "s" 


) 

apply state 

version 1 
end declare 


3.19 Output Shaders 


Output shaders are functions that are run after rendering has finished. They modify the resulting 
image or images. Typical uses are output filters and compositing operations. Output shaders can 
directly access all rendered frame buffers and make modifications to these frame buffers, but they 
do not return a result like other shaders do. They still get a result pointer as their first argument, 
for symmetry with the other types of shaders, but this pointer should not be used. 


Until version 2.0.20 of mental ray, output shaders had a different prototype (there was no result 
pointer argument) and a different state called miOutstate, which contained frame buffers but 
very few other state variables, so output shaders could not use any shader interface function 
that required an argument of type miState. For backwards compatibility, these shaders are still 
supported, but not recommended and not described in this book. mental ray distinguishes old- 
style output shaders by a null or missing version number in the declaration. Old-style output 
shaders did not support shader initialization and cleanup and the mz_eval family of functions; 
new ones do. 


It is important to specify a non-null shader version number in the declaration of output shaders! 
If none is specified, mental ray issues a warning and calls the output shader with an miOutstate, 


which will probably crash it. 


All output shaders must be declared like any other type of shader, and the same types of arguments 
can be declared. This includes textures and lights. Nonprocedural textures can be looked up using 
functions like mi_lookup color_texture and mi_query. Lights can also be looked up with mz query. 
Since rendering has completed, it is not possible to look up procedural textures or to use tracing 
functions such as mi_sample_light. 
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Here is a simple output shader that depth-fades the rendered image towards total transparency: 


struct out_depthfade { 


= Q; 


/ (tfar - tnear); 


miScalar tnear ; /* no fade closer than this */ 
miScalar  tfar; /* farther objects disappear */ 
tr} 
miBoolean out_depthfade ( 
void *result, 
register miState *state, 
struct out_depthfade *paras) 
{ 
register int x, 93 
miColor color: 
miScalar depth, fade; 
miScalar tnear, tfar; 
milmg_image *fb_color, *fb_depth; 
tnear = *mi_eval_scalar(&paras->tnear) ; 
tYfax = *mi_eval_scalar(&paras->tfar) ; 
fb_color = state->options-—>image [miRC_IMAGE_RGBA] .p; 
fb_depth = state->options->image [miRC_IMAGE_Z] .p; 
for (y=0; y < state->camera->y_resolution; y++) { 
if (mi_par_aborted()) 
break; 
for (x=0; x<state->camera->x_resolution; xt++) { 
mi_img_get_color(fb_color, &color, x, y); 
mi_img_get_depth(fb_depth, &depth, x, y); 
if (depth >= tfar || depth == 0.0) 
color .r=color.g=color.b=color.a 
else if (depth > tnear) { 
fade = (tfar - depth) 
color.r *= fade; 
color.g *= fade; 
color.b *= fade; 
color.a *= fade; 
} 
mi_img_put_color(fb_color, &color, x, y); 
‘ 
I 
return (miTRUE) ; 
} 


Note the call to mi_par_aborted, which stops the shader if the user has instructed mental ray 
to stop whatever it is doing. This call was inserted in the line loop because it should be called 
periodically, but not too often to avoid slowing it down. Also, note that the parameters are named 
tnear and tfar instead of near and far because some older early-1980’s compilers reserve these 


as keywords. 
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This shader is stored in a file out_depthfade.c and installed in the .mi file with a code statement 
and a declaration: 


code "out_depthfade.c" 

declare shader 
"out_depthfade" (scalar "near", scalar "far") 
version 1 

end declare 


Frame buffer access has changed substantially in mental ray 3.4. For example, to access the RGBA 
color and Z depth frame buffers, it is necessary to open and close the frame buffers instead of 
reading their tags from the state: 


milmg_image *fb_color = mi_output_image_open(state, miRC_IMAGE_RGBA) ; 
miImg_image *fb_depth = mi_output_image_open(state, miRC_IMAGE_Z) ; 


mi_output_image_close(state, miRC_IMAGE_Z) ; 
mi_output_image_close(state, miRC_IMAGE_RGBA) ; 


See the definition of mi_output_image_open?* for details. This method allows an arbitrary number 
of frame buffers, not just 13 as in mental ray 3.3 and earlier. 


It is actually more efficient to precompile the shader, store it in a DSO file, and use the link 
statement instead of code. See the beginning of this chapter (page 185) for details. The declaration 
should appear before the first reference to the shader in a camera statement. Note the non-null 
version statement. The shader is referenced in an output statement in the camera: 


camera "cam" 
output "rgba,z" "out_depthfade" 
(“near" 10.0, “far 100.0) 
output "rgb" "filename.rgb" 
samples 0 1 


end camera 


Note that the output shader statement appears before the output file statement. The output shader 
must get a chance to change the output image before it is written to the file filename.rgb. It is 
possible to insert another file output statement before the output shader statement; in this case 
two files would be written, one with and one without depth fading. 


Note also that the output shader has a type string "rgba,z". This string tells mental ray to render 
both an RGBA and a Z (depth) frame buffer. The RGBA buffer would have been rendered 
anyway because the file output statement requires it, but the depth buffer would not have been 
rendered without the z in the type string. In this case, all depth values returned by miimg_get- 
depth would be 0.0. 
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By default, depth buffers are not interpolated; instead the min depth within the pixel is used. If 
the depths should be interpolated, use the output type "rgba,+z". Refer to the Functionality 
chapter for more information on frame buffer interpolation. 


This shader does not anti-alias very well because there is only one depth value per pixel. The 
shader makes pixels for which a depth of 0.0 is returned totally transparent to fade edges of 
objects correctly that have no other object behind them. By definition, miimg_get_depth returns 
0.0 for a position x, y if no object was hit at that pixel. 


3.20 Displacement Shaders 


Displacement shaders are called during geometry tessellation if the material of a polygonal or free- 
form surface object specifies a displace shader. Whenever the tessellator introduces or copies 
a vertex, the displacement shader is called and expected to return a scalar value that tells the 
tessellator to move the vertex by this distance along its normal vector. If 0 is returned, the vertex 
remains unchanged. If the object specifies displacement approximations, curvature introduced 
by displacement can lead to further subdivision. Here is an example: 


struct mydisplace { 


miTag tex; 
miScalar factor; 
}; 
miBoolean mydisplace( 
miScalar *result, 
miState *state, 
struct mydisplace *paras) 
{ 
miColor color; 
mi_lookup_color_texture(&color, state, 
*mi_eval_tag(&paras->tex) , 
&state->tex_list[0]); 
*xresult += (color.r + color.g + color.b) / 3 * 
*mi_eval_scalar (&paras->factor) ; 
return (miTRUE) ; 
} 


Note that the shader adds its displacement to the result instead of storing it. This allows chaining 
displacement shaders in shader lists. Shaders in shader lists get called in sequence, each adding its 
contribution to the result of the previous. mental ray calls the first displacement shader of the list 
with a result that is initialized to 0. 


Displacement shaders may also change the vector state + normal along which the displacement 
will take place, or change state — point, which is the original vertex position that the displacement 
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is added to. However, note that mental ray does not check that surfaces resulting from such 
arbitrary displacements are free of self-intersections. 


mental ray 3.x requires that an object that is displaced with a displacement shader must contain a 
max displace statement that specifies the maximum displacement of the object. This is the largest 
absolute value that any displacement shader may return. For example, if the max displace value 
is 2.5, then no displacement shader may move the surface more than 2.5 units in any direction. 
For typical displacement shaders that return a value but do not change state — point, this means 
that the displacement shader must return a value in the range [-2.5, 2.5]. mental ray 3.x will 
print warning messages if the shader returns a value outside this interval because this can cause 


geometry to be clipped. 


mental ray 3.1.2 and later allows the displacement shader to store a motion vector in state > 
motion. This vector will be interpreted as the motion of the displaced point relative to the original 
point on the undisplaced base surface. This allows motion blurring of the displacement, if the 
displacement changes rapidly between frames. This requires that motion blurring is enabled, and 
that the object has motion vectors or motion transformations (the displacement motion is added 
to the motion of the underlying surface). 


mental ray 3.3 and later make first derivatives available in the state for displacement shaders. 
Also, the result pointer passed to displacement shaders when displacing subdivision surfaces now 
points to cleared memory; this is useful for displacement shader chains where each shader adds 
to the result of the previous shader. 


3.21 Geometry Shaders 


Geometry shaders are functions that procedurally create geometric objects. They are different 
from most of the shaders described here because they do not return a color, but a miTag reference 
to the object or instance group created by the shader. The geometry shader is called with a 
miState containing valid fields for camera, options, current shader, and version. The shader 
parameters are passed as the third argument. The geometry shader is expected to return the tag 
of the object or instance group it creates. 


Here is a simple example for a geometry shader that creates a single triangle. A more robust 
shader would check the return values of all function calls made here. Geometry shaders use a 
special set of shader interface functions to create geometry. All these functions begin with mz- 


apt-. 


static void add_vector(miScalar x, miScalar y, miScalar z) 


{ 
miVector v; 
T.X¥ = =i v.y = yi ¥.2 = Z; 
mi_api_vector_xyz_add(&v) ; 
} 


miBoolean geotriangle( 
miTag *result, 
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miState *state, 
miTag *paras) 


miO0bject *Obj ; 


obj = mi_api_object_begin(NULL) ; 

obj->visible = obj->shadow = obj->trace = miTRUE; 
mi_api_basis_list_clear() ; 
mi_api_object_group_begin(0.0) ; 


add vector(-1., 0., 0.); 
add vector( 1., 0., 0.); 
add_vector( 0.,; 0., 1.) 
mi_api_vertex_add(0) ; 
mi_api_vertex_add(1) ; 
mi_api_vertex_add(2) ; 


mi_api_poly_begin_tag(1, *mi_eval_tag(paras)) ; 
mi_api_poly_index_add(0) ; 
mi_api_poly_index_add(1) ; 
mi_api_poly_index_add(2) ; 

mi_api_poly_end() ; 


mi_api_object_group_end() ; 
return(mi_geoshader_add_result (result, mi_api_object_end() )); 


In this example an unnamed object is created with the flags visible, shadow and trace set to miTRUE, 
a caustic mode set to 0, and a label 0. In the mandatory object group a triangle is constructed with 
API calls. The material of the triangle is assigned from the shader parameters. The object group 
definition is finalized with the polygonal information argument set to miTRUE. 


The following example is more complex. It creates multiple sub-instances, each referencing a 
placeholder object’*. The sub-instance transformation matrices are set so that the objects form 
a ring. Since only placeholders are created, mental ray will not create all their triangles up front 
but merely watch their bounding boxes (also set by the geometry shader), and when a ray hits 
the bounding box the placeholder object will be created by calling the installed callback function, 
makeobyect. 


This is a very efficient way of creating geometry in a geometry shader. It allows mental ray to 
store small and simple placeholders in the scene, and generate the objects only when they are 
needed, and remove them from the cache when they are no longer needed. Instead of blocking 
large sections of memory, only the geometry actually needed is stored, and if an object is never 
seen because it is hidden by another or off-screen, it will never be loaded or tessellated. 


#include <stdlib.h> 
#include <string.h> 
#include <math.h> 

#include <shader.h> 
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#include <geoshader.h> 
static miBoolean makeobject(miTag, void *); 


typedef struct { 


miScalar radius; 
int nobjects; 
} Multgeo; 


DLLEXPORT int wreath_version(void) {return(1) ;} 


DLLEXPORT miBoolean wreath( 


miTag *result, 

miState *Sstate, 

Multgeo *paras ) 

4. 

int i, num = *mi_eval_integer(&paras->nobjects) ; 

miScalar radius = *mi_eval_scalar (&paras->radius) ; 

miScalar angle; 

milnstance *inst; 

miObject *obj; 

char oname[100], iname[100]; 

for (i=0; i < num; itt) { 
/* placeholder object */ 
sprintf(oname, "wreath/x_objjd", state->shader, i); 
obj = mi_api_object_begin(mi_mem_strdup(oname) ) ; 
obj->visible = obj->trace = obj->shadow = miTRUE; 
obj->bbox_min.x = obj->bbox_min.y = obj->bbox_min.z = -1; 
obj->bbox_max.x = obj->bbox_max.y = obj->bbox_max.z = 1; 
mi_api_object_callback(makeobject, 0); 
mi_api_object_end() ; 
/* instance */ 
sprintf(iname, "wreath/x_inst%d", state->shader, i); 
inst = mi_api_instance_begin(mi_mem_strdup(iname) ) ; 
mi_matrix_ident (inst->tf.global_to_local) ; 
angle = 2 * M_PI * i / num - M_PI; 
inst->tf.global_to_local[12] -= sin(angle) * radius; 
inst->tf.global_to_local[13] += cos(angle) * radius; 
mi_matrix_invert (inst->tf.local_to_global, 

inst->tf.global_to_local) ; 
mi_geoshader_add_result (result, 
mi_api_instance_end(mi_mem_strdup(oname), 0, 0)); 
} 
return (miTRUE) ; 
} 


static void add_vector(miScalar a, miScalar b, miScalar c) 
{ 
miVector v; v.x=a; v.y=b; v.Z=c; 
mi_api_vector_xyz_add(&v) ; 
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static void add_triangle(int a, int b, int c) 
{ 
mi_api_poly_begin_tag(1, 0); 
mi_api_poly_index_add(a) ; 
mi_api_poly_index_add(b) ; 
mi_api_poly_index_add(c) ; 
mi_api_poly_end() ; 
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t 
#define USUB 32 
#define VSUB 16 
static miBoolean makeobject ( /* create the geometry for a placeholder */ 
miTag tag, /* create this tag (by name) */ 
void *xarg) /* 2nd arg of mi_api_object_callback */ 
{ 
miVector V3 
miInteger i, j, nv=0; 
miScalar Ds 33 
miQbject *obj; 
const char *xoname = mi_api_tag_lookup(tag) ; 


mi_info("creating object %s\n", oname) ; 
mi_api_incremental (miTRUE) ; 
obj = mi_api_object_begin(mi_mem_strdup(oname) ) ; 


obj->visible = obj->shadow = obj->trace = miTRUE; 


mi_api_object_group_begin(0.0) ; 
for (i=1; i <= VSUB; i++) { 
v.z = -cos(i * M_PI / (VSUB+1)); 


r = sqrt(1. - v.z¥v.z); 

for (j=0; j < USUB; j++, nv++) { 
p = j * 2 x* M_PI rd USUB; 
v.x =r * cos(p); 
v.y =x * sin(p); 


mi_api_vector_xyz_add (kv) ; 
mi_api_vector_xyz_add (kv) ; 
} 
: 
add_vector(0, 0, -1); 
add_vector(0, 0, -1); 
add_vector(0, 0, +1); 
add_vector(0, 0, +1); 
for {i=0; 1 < nv: 14+) 4 
mi_api_vertex_add(i*2) ; 
mi_api_vertex_normal_add(i*2+1) ; 
} 
mi_api_vertex_add(nv*2+0) ; 
mi_api_vertex_normal_add(nv*2+1) ; 
mi_api_vertex_add(nv+*2+2) ; 
mi_api_vertex_normal_add(nv*2+3) ; 
for (j=0; j < USUB; j++) 
add_triangle(nv, (j+1)%USUB, j); 


/* point */ 
/* normal */ 


/* south pole */ 


/* north pole */ 


/* south pole */ 
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for (j=0; j < USUB; j++) 
add_triangle(nv+1, nv-USUB+j, nv-USUB+((j+1)ZUSUB) ) ; 
for (i=0; i < VSUB-1; i++) 
for (j=0; j < USUB; j++) f 


int pl 
int p2 
int p3 
int p4 


/* north pole 


i*USUB + j; 

i*USUB + (j+1)%USUB; 
(i+1)*USUB + (j+1)ZUSUB; 
(i+1)*USUB + j; 


add_triangle(pi, p2, p4); 
add_triangle(p2, p3, p4); 


} 


mi_api_object_group_end() ; 
mi_api_object_end() ; 


return (miTRUE) ; 


*/ 
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This particular example is contrived because the makeobject shader creates the same sphere every 
time, so multiple instancing of a single object would have been more efficient. Here is a simple 
scene that uses this shader: 


verbose on 
link "base.so" 
$include "base.mi" 


link "geosh.so" 
declare shader 


geometry "wreath" ( 


scalar 


integer 


version i 
end declare 


options "opt" 
samples 
object space 
end options 


camera "cam" 
frame 
output 
focal 
aperture 
aspect 
resolution 

end camera 


instance "cam_inst" 
transform 


"radius", 
"nobjects") 


a 


1 

"rgb" "out.rgb 
30 

4é 

1 

500 500 


"cam" 

0.7719 0.3042 
0.0000 0.8781 
0.6357 -0.3693 
0.0000 -1.0000 


288 3 Using and Writing Shaders 


end instance 


light "light1" 
"mib_light_point" ("color" 1 1 1) 
origin -50 50 0 

end light 


instance "light_inst" "lighti" end instance 
material "mt1" 


"mib_illum_phong" ( 
"exponent" 50 


"ambient" 0.5 0.5 0.6, 
"diffuse" wt Oe ek, 
"specular" 1.0 1.0 1.0, 
"ambience" 0.3 0.3 0.3, 
"lights" ["light_inst"] 


) 


end material 


instance "geo_inst0" 
geometry "wreath" ("radius" 10, "nobjects" 36) 
material "mtl" 

end instance 


instance "geo_inst1" 
geometry "wreath" ("radius" 10, "nobjects" 36) 
material "mt1" 
transform 0010 0100 1000 0001 
end instance 


instance "geo_inst2" 
geometry "wreath" ("radius" 10, "nobjects" 36) 
material "mtl1" 
transform LVeood-.ocgc10 O2100 OOO 
end instance 


instgroup "rootgrp" 
"cam_inst" "light_inst" "geo_inst0O" "geo_inst1" "geo_inst2" 


end instgroup 


render "rootgrp" "cam_inst" "opt" 
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Here is the resulting image: 


Note that the default assumption for the geometry type is traditional geometry like polygons or 
NURBS. If hair geometry is needed, an extra step is required if setting up a callback function. 
Here is an example: 


miTag tag; 
miObject *obj; 


obj = mi_api_object_begin(mi_mem_strdup(obj_name)) ; 
mi_api_object_callback(obj_cb, (void *) args) ; 
tag = mi_api_object_end() ; 


obj = (mi0bject *)mi_scene_edit (tag) ; 
obj->geo.placeholder_list.type = miOBJECT_HAIR; 
mi_scene_edit_end(tag) ; 


Note that all scene elements created by a geometry shader are ina special scope that will be deleted 
later, when rendering has finished and the scene is postprocessed. That means that a geometry 
shader cannot generally incrementally change scene database elements that it has created in a 
previous frame. 


3.22 Contours 


The use of flexible, user-defined contour shaders opens up the possibility of many new effects. 
User-specified functions and shaders determine where the contours should be and compute 
contour colors and widths. These computations can be based on any information about the 
geometry, illumination, and materials of the scene, for example Z depth, Z depth difference, 
orientation, curvature, light source directions, material color, fog, etc. 
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The list of possible contour shaders is endless. A few ideas for contour shaders are: different 
styles of contour lines such as hand-drawn pencil, chalk, calligraphic pen, brush, wiggly lines, 
dashed lines, etc; contours between areas in shadow and areas not in shadow; contour parameters 
depending on motion information; highlights on contours to indicate curving edges. 


The following is a detailed description of how contours are computed, and how the contour 
store shader, the contour contrast shader, and the contour shaders are called. Note that contour 
shaders do not follow the normal shader argument conventions. They do support initialization 
and exit shaders with standard init/exit shader prototypes and semantics. They are not called 
during final gathering preprocessing’ and light mapping>*. 


3.22.1 Contour Computation 


A regular color image is created by recursively sampling the scene, that is, casting rays into the 
geometry. The same samples are used to generate the contours. With each sample, some user- 
specified information is stored by the user-specified contour store function, information that is 
used later for determining the locations, colors, and widths of the contours. The contour store 
function is called right after the material shader and saves information such as ray intersection 
point, the normal at the intersection point, object tag, material color, refraction level, etc. 


During recursive sampling, the decision whether to take additional samples is based on the 
comparison of two adjacent samples. New samples are taken if the color contrast is sufficiently 
large (as defined by the regular contrast, for moving objects, or if a user-specified contour contrast 
shader returns miTRUE. The contour contrast shader can base its decision on any information that 
was stored by the contour store function for the two sample points. For example, the contour 
contrast function could return miTRUE if their depths or orientations differ much. 


When two samples are at minimum distance (according to the value of the max samples 
parameter), and their contour contrast is still high (that is, the contour contrast shader returns 
miTRUE), mental ray assumes that a contour must be drawn between the two samples and calls 
a user-specified contour shader. The contour shader computes the contour color and width 
depending on, for example, curvature (orientation difference), Z depth, Z depth difference, 
material color, or some other information saved by the contour store shader. The contour shader 
of the object closest to the camera is used. If no contour shader is specified for the material, it 
does not get a contour. The computed contour point data (contour color, width, etc.) for each 
point on the contour is stored in a temporary data structure. mental ray merges these contour 
points into straight contour line segments, each represented by its two endpoints. 


These contour line segments are received by a contour output shader in a postprocessing step. 


The contour output shader reads the contour segment endpoints and generates, for example, an 
image or a PostScript file. 


3.22.2 Contour Store Function 


The contour store shader stores various information needed for contour computations. The input 
is the regular state after ray intersection and the call of material shader, and the color resulting 
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from the material shader call. The output is the information the user deems necessary to compute 
contours, and the size of this information. There is only one global contour store shader for a 
scene. The contour store function’s job is to collect all information that the contour contrast 
function needs to decide where to put contours and that the contour shaders need to draw a 
contour. 


To give an example of a contour store shader, assume you have decided that to compute contours, 
you need the ray intersection point, the normal vector, the material, and the color at that point 
as computed by the material shader (which means the color is not just the color of the material 
with the given illumination; it also includes reflected and refracted light). Then define the data 
type MyInfo as 


typedef struct MyInfo { 


miVector point; /* ray intersection point */ 
miVector normal; /* ray intersection normal */ 
miTag material; /* material tag */ 
miColor color: /* from material shader */ 

} MyInfo; 


Here is a contour store shader that fills in these fields of MyInfo: 


miBoolean my_contour_store_function( 
void *info_void, 
int *info_size, 
miState *state, 
miColor *color) 


{ 
struct MyInfo *info = (MyInfo *)info_void; 
info->point = state->point; 
info->normal = state->normal; 
info->material = state->material; 
info->color = *color; 
*xinfo_size = sizeof (MyInfo) ; /* for mental ray 2.x */ 
return(miTRUE) ; 
t 


mental ray will store a MyInfo data structure with every sample until the contour contrast shader 
is called. The number of stored MyInfo data structures grows up to the number of samples taken 
in an image task (typically a 32 x 32 pixel block). 


Note that mental ray 3.x requires that the contour store shader is declared correctly: 


declare shader 
struct { 
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vector "Deane 
vector "normal", 
material "material", 
color "color" 


} "out_depthfade" (scalar "near", scalar "far") 
version 1 
end declare 


mental ray 2.x ignored the return type and required that the shader assigns the size of the returned 
data in *info_size. This will no longer work with mental ray 3.x, which must know the return 
size in advance, and therefore requires a correct declaration. mental ray 3.x will print an error 
message if the return type declaration is missing and allocates space for one color, but in this case 
this would not be enough, so the shader would crash! 


3.22.3 Contour Contrast Function 


The contour contrast shader decides where the contours should be. For example, it might decide 
that there should be a contour when the difference in depth or orientation is large. The decision 
is based on the contour information for two points (the information saved by the contour store 
shader), the reflection or refraction level of the two points, the state, and the parameters of the 
contour contrast function. Note that the state does not contain intersection information because 
the contrast function is comparing two intersections, described solely by the information stored 
by the two contour store functions. This means that state variables such as point or tex_list are 
undefined in a contrast function. 


The output is a Boolean value indicating whether there should be a contour between the two 
points. If the returned value is miTRUE, one of two things can happen: If the distance between 
the two points corresponds to max samples, a contour will be placed between the two points 
(getting contour width, color, etc. by calling the material’s contour shader). If not, mental ray 
will take some additional samples to get a more precise position of the contour. There is only one 
contour contrast shader for the scene. 


As an example of a user-defined contour contrast shader, consider the following function with 
parameters zdelta and ndelta: 


miBoolean my_contour_contrast_function( 


MyInfo *infol, 
MyInfo *info2, 
int level, 
miState *Sstate, 


My_Contour_Contrast_Parameters ¥*paras) 


/* 

* Contour if one ray intersected an object and one 
* ray hit background 

*/ 

if (!infol || !info2) 
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return (miTRUE) ; 
/* 
* Contour if sufficiently large difference in depth 
*} 


if (fabs(info1->point.z - info2->point.z) > 
paras->zdelta) 


return (miTRUE) ; 
/* 
* Contour if sufficiently large change in normal 
m/f 


if (mi_vector_dot(&infoi->normal, &info2->normal) < 
cos(paras->ndelta * M_PI/180.0)) 
return (miTRUE) ; 


/* 
* No contour otherwise 
* / 

return(miFALSE) ; 


3.22.4 Contour Shaders 


The contour shaders compute contour color and width (and optionally object label, material tag, 
motion, and normal). Their input is two contour information blocks for two adjacent samples on 
each side of a contour (as stored by the contour store shader), the state, and shader parameters. 
Each material can have a separate contour shader. If no contour shader is specified for a material, 
that material does not get a contour. 


The contour shader to call is selected based on which object is in front. If the difference in depth 
is small, the selection is based on which object faces the camera the most. (This is necessary to 
avoid “randomly” mixing contours along an edge between two different materials.) 


As an example, consider the following very simple contour shader. It makes the contours white 
and half a percent (of the image X resolution) wide: 


miBoolean my_first_contour_shader ( 
miContour_endpoint *result, 


MyInfo *info_near, 
MyInfo *info_far, 
miState *Sstate, 
void *paras) 


result->color.r = result->color.g 
result->color.b = result->color.a 
result->width = 0.5; 

return (miTRUE) ; 


II 
= 
oe) 
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The type of the result is 


typedef struct { 
miVector point; 
miColor color; 
float width; 
miVector motion; 
miVector normal; 
miTag material; 
int label; 

} miContour_endpoint ; 


The point is automatically filled in, the contour shader does not have to do that. point.x and 
point.y are in screen coordinates, while point .z is in camera coordinates. 


An example of a slightly more complex shader, where the contour color is a factor of the material 
color and the width is a parameter, is 


miBoolean my_colordependent_contour_shader ( 


miContour_endpoint *result, 

MyInfo *info_near, 

MyInfo *info_far, 

miState *state, 

Factorcolor_Parameters *paras) 

4 

/* 
* Set contour color to a factor times material color. 
* The opacity color->a is set to 1.0, otherwise the 
* material will shine through the contour. 
*/ 

float f = paras->factor; 

result->color.r = f * info_near->color.r; 

result->color.g = f * info_near->color.g; 

result->color.b = f * info_near->color.b; 

result->color.a = 1.0; 

/* 
* Contour width given by a parameter 
+ / 

result->width = paras->width; 

return (miTRUE) ; 

: 


An appropriate data type must be defined for a contour shader. In this case, the data type of the 
parameters, Factorcolor_Parameters, contains the fields factor and width. 
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3.22.5 Contour Output Shaders 


Output shaders are called after the image has been computed. An output shader can use the 
function mi_get_contour_line to get endpoints of a contour. When mi_get_contour_line returns 
miFALSE, there are no more contour lines. 


Here is a very simple output shader that prints the screen-space coordinates of the contour 
endpoints. 


miBoolean my_contour_output_shader ( 
miColor *result, /* unused */ 
miState *state) 
/* no parameters */ 


1 
miContour_endpoint pl; 
miContour_endpoint p2; 
mi_info("Contour endpoints:"); 
/* Get and write the contour endpoints */ 
while (mi_get_contour_line(&p1, &p2)) 
iW anmtot"7s -f ~=— AE 7", pi.point.=, pi.poine.y, 
p2; point .x,- p2. point. 7); 
return (miTRUE) ; 
t 
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Lightmap shaders can be attached to materials to sample the object that the material is attached 
to, and compute a map that contains information about the object. The most common application 
is sampling illumination, or just indirect illumination, and storing it into a writable texture file 
that can be texture-mapped later during rendering. This makes rendering much faster, although 
the illumination contribution is now frozen into the object and cannot change with changing 
lighting conditions. 


Lightmap shaders are called in two different modes: 


e In vertex mode, state — type is miRAY_LM_VERTEX. mental ray will call the shader in this 
mode once for every triangle vertex. The shader is expected to collect data about the object 
in this mode. 


e Inmesh mode, state — type ismiRAY_LM_MESH. After all vertex samples have been taken, the 
shader is called once in mesh mode. It can now use the collected information to generate 
the final output. 
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This section describes the lightmap shaders in the base shader library that is included with mental 
ray. It puts direct, and optionally also indirect, illumination into a writable texture. It is split into 
two shaders, and mib_lightmap-_sample, to make it easy to write a new sampling function without 
having to rewrite the entire lightmap shader. The sample shader is attached to the main shader as 
a shader parameter. 


In vertex mode, the main shader could simply sample the illumination and store it in the texture, 
but this would result in a texture with only a few isolated dots. (This might be a good approach 
for generating vertex color for a hardware game engine though.) The shader could also sample 
and save the illumination and during vertex mode and then paint triangles into the texture in mesh 
mode by interpolating these points, but this would result in very coarse lightmap. Therefore, the 
standard shader in the base shader library that comes with mental ray and that is listed below 
only collects point, normal, and texture coordinates in vertex mode, and paints triangles during 
mesh mode by sampling for every written pixel. 


Here is the standard lightmap base shader: 


#define mi_MIN(a,b) ({a) < (b) 7 Ca) : (b)) 
#define mi_MAX(a,b) ({a) > (b) f Ga) ¢ (by) 
#define mi_MIN3(a,b,c) ((a) < (b) ? mi_MIN(a,c) : mi_MIN(b,c)) 
#define mi_MAX3(a,b,c) ((a) > (b) ? mi_MAX(a,c) : mi_MAX(b,c)) 


typedef struct mib_lightmap_write_result{ 


miVector point; /* point in space */ 
miVector normal ; /* vertex normal */ 
miVector tex; /* texture coordinates of vertex */ 


} mib_lightmap_write_result; 


typedef struct mib_lightmap_write_param{ 


miTag texture; /* writable texture */ 
miTag coord; /* texture coordinate shader */ 
miTag sample_sh; /* sampling shader */ 


} mib_lightmap_write_param; 


DLLEXPORT miBoolean mib_lightmap_write( 
mib_lightmap_write_result *result, 
miState *xstate, 
mib_lightmap_write_param *param, 
miRclm_mesh_render const *arg) /* argument */ 


{ 
int 2 
mib_lightmap_write_result const *resdata; 
milmg_image *img ; 
miTag tex_tag; 
miTag shader_tag; 
miTag coordshader_tag; 
void *handle; 
miBoolean success; 


switch (state->type) { 
case miRAY_LM_VERTEX: 
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/* Gathering vertex data */ 
result->point = state->point; 
result->normal = state->normal; 
mi_vector_normalize(&result->normal) ; 
coordshader_tag = *mi_eval_tag(&param->coord) ; 
/* need co call the shader to get access to the success value*/ 
success = mi_call_shader_x((miColor*) &result->tex, 
miSHADER_TEXTURE, state, coordshader_tag, 0); 

if (!success) 

result->tex.x = -1; /* mark this vertex as bad */ 
break; 


case miRAY_LM_MESH: 


i 


if (!arg) 
return (miFALSE) ; 


tex_tag = *mi_eval_tag(&param->texture) ; 
shader_tag *mi_eval_tag(&param->sample_sh) ; 


if ('!tex_tag || !shader_tag) 
return (miFALSE) ; 


if (! (img = mi_lightmap_edit(&handle, tex_tag))) 
return (miFALSE) ; 


resdata = (mib_lightmap_write_result const *)arg->vertex_data; 


for (i=0; i < arg->no_triangles; i++) 
mib_lightmap_do_triangle(state, img, 

arg->pri, arg->triangles[i].pri_idx, 
&resdatalarg->triangles[i].al], 
&resdatalarg->triangles[i].b], 
&resdatalarg->triangles[i].c], 
shader_tag) ; 

mi_lightmap_edit_end (handle) ; 


return (miTRUE) ; 
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Note the use of the texture access functions mi_lightmap_edit and mi_lightmap-edit_end, which 
give the shader writing access to the writable texture. The texture must be defined with the 
writable flag for this to work. It is not sufficient to use standard access functions like mi_db_ 
access because they do not permit writing access, and because they would not cause the finished 
texture to be written to disk. 


In mesh mode, mental ray uses the fourth argument arg of the lightmap shader to pass triangle 
information and the data collected in vertex mode: 


typedef struct miRclm_mesh_render { 


void 


int 


*pri1; 
no_triangles; 
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miRclm_triangle const *triangles; 
void const *vertex_data; 
} miRclm_mesh_render; 


typedef struct miRclm_triangle { 


milnteger a; 
miInteger b; 
milInteger oo 
miGeoIndex pri_idz; 


} miRclm_triangle; 


The vertex_data is an array of the data blocks stored by the lightmap shader in vertex mode. The 
triangles array contains no_triangles records of the type miRclm_triangle. The shader will loop 
over these triangles, scan-converting each into the writable texture. Each triangle has three vertex 
indices that are indices into the vertex_data array. For example, to find the data that the lightmap 
shader has stored when it was called for the first vertex of the fifth triangle, it uses this expression: 


typedef struct {...} Stored; 
Stored *list (Stored *)arg->vertex_data; 
Stored *vertex = &list[arg->triangles[5] .a]; 


This assumes that the fourth shader argument is named arg. The opaque p7i pointer identifies 
the object that is being lightmapped. If the shader needs to cast rays or call other mental ray 
functions, it should store this pointer in state — pri, and also store the prizdx in the miRclm_ 
triangle struct in state — priidx. 


The data collected in vertex mode is stored in vertex_data by mental ray. For this to work, the 


main shader must be declared correctly with all return variables, so that mental ray knows how 
many bytes to allocate: 


declare shader 


struct { 
vector “point”, 
vector "normal", 
vector "tex" 
} 
"mib_lightmap_write" ( 
color texture "texture", # output texture 
vector texture "coord", # texture coords to use 
color texture "input" # evaluated texture 
) 


version 1 
end declare 


Here is the lightmap sample shader that generates colors for the main lightmap shader to store 
into the writable texture. It simply computes the light irradiance at the current intersection point. 
It relies on the point, normal, and tex data stored in mesh mode. 
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typedef struct mib_lightmap_sample_param{ 


miBoolean indirect; /* do indirect illumination? */ 
int flip; /* flip normals? */ 

int 2 JI gat; 

int n_light ; 

miTag light [1]; /* lights to sample */ 


} mib_lightmap_sample_param; 


DLLEXPORT miBoolean mib_lightmap_sample( 


miColor *result, 

miState *state, 

mib_lightmap_sample_param *param) 
{ 

int i_light ; 

int n_light ; 

miTag *light ; 

miColor color, sum; 

int 1) at 

int tla; 

int times; 

flip = *mi_eval_integer (&param->flip) ; 


i_light = *mi_eval_integer (&param->i_light) ; 
n_light = *mi_eval_integer (&param->n_light) ; 
light = mi_eval_tag(param->light) + i_light; 


times = flip==2 7 2: 1; 


result->r = result->g = result->b = 0.0f; 
for (m=0; m<times; mt+) { 
if (flip == 1 || m==1) { 
mi_vector_neg(&state->normal) ; 
mi_vector_neg(&state->normal_geom) ; 
} 
for (1=0; 1 < n_light; 1++) { 
miVector dir; 
miScalar dot_nl; 
int samples = 0; 


sum.r = sum.g = sum.b = 0.0f; 
while (mi_sample_light(&color, &dir, &dot_nl, 
state, light[1], &samples)) f{ 

sum.r += dot_nl * color.r; 
sum.g += dot_nl * color.g; 
sum.b += dot_nl * color.b; 

} 

if (samples) { 
result->r += sum.r / samples; 
result->g += sum.g / samples; 
result->b += sum.b / samples; 


} 


/* indirect illumination */ 
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if (*mi_eval_boolean(&param->indirect)) { 


} 


if (flip >= 0) { 


mi_compute_irradiance(&color, state) ; 


result->r += color.r; 
result->g += color.g; 
result->b += color.b; 


mi_vector_neg(&state->normal) ; 
mi_vector_neg(&state->normal_geom) ; 


} 


result->a = 1.0f; 


return (miTRUE) ; 
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The main shader uses a static function to scan-convert triangles in mesh mode. The following 
function paints a single triangle into the writable texture, evaluating illumination for every painted 
pixel. The triangle extents are determined in pixel space. Next, a mapping from pixel space to 
barycentric coordinates is computed, and a loop over the pixels whose centers fall within the 
triangle performs the actual sampling. This is done by using a scanline approach where a line pair 
is generated for the upper and lower part of the triangle. This makes certain that inside detection 
for adjacent triangles is handled identically and so no pixels are missed. For each such center an 
intersection is computed and a source shader called to get a value which is then stored in the 


writable texture. 


typedef struct Line2d { 


float 
float 
} Line2d; 


ae /* slope */ 
o: /* offset */ 


static void mib_lightmap_do_triangle( 


miState 
milmg_image 
void 
miGeoIndex 


*State, 
*img, 
*pri, 
pri_idx, 


mib_lightmap_write_result const *a, 
mib_lightmap_write_result const *b, 
mib_lightmap_write_result const *c, 


miTag shader_tag) 
miVector pixa, pixh,. pixc; 
miMatrix tmp1, tmp2; 
miMatrix pixel_to_bary; 
miVector p; 

miVector Gl, Ge: 

miVector const *pix_y[3], *tmp; 
Line2d line [3] ; 


Line2d const *left[2], *right [2]; 
float y_min, y_max; 
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miBoolean long_right ; 


/* give up if any of the vertices was marked as not-to-use */ 
if (a->tex.x < 0 || b—>tex.x < 0 || c->tex.&. « 6) 
return; 
/* 
* compute pixel coordinates from texture coordinates. They are offset 
* by half so that integer values land in the center of the pixels. 


*/ 
pixa.x = a->tex.x * img->width - 0.5f; 
pixb.x = b->tex.x * img->width - 0.5f; 
pixc.x = c->tex.x * img->width - 0.5f; 
pixa.y = a->tex.y * img->height - 0.5f; 
pixb.y = b->tex.y * img->height - 0.5f; 
pixc.y = c->tex.y * img->height - 0.5f; 
pix_y[0] = &pixa; /* sort vertices in y increasing order */ 


pix_yl1] = &pixb; 
pix_y[2] = &pixc; 
if (pix_y[0]->y > pix_y[1]->y) { 
tmp = pix_y[0]; pix_y[0] = pix_y[1]; pix_y[1] = tmp; 
} 
if (pix yll]—>y > piscyl2]-—>y) I 
tmp = pix_y[1]; pix_y[l1] = pix_yl2]; pix_y[2] = tmp; 


; 
if (pix_yl0]->y > pix.yiil—y) 
tmp = pix_y[0]; pix_y[0] = pix_y[1]; pix_y[1] 


tmp ; 
} 


if (pix_y[0]->y >= pix_y[2]->y) /* avoid empty triangles */ 
return; 


/* compute lines */ 
line[0].s = (pix_y[1]->x: —pix_y[0]->x); /| (piz.y(1]—>y — piz_yl0]->y); 
line[0].o = pix_y[0]->x - pix_y[0]->y * line[0].s; 


line(1].a = (pix_y[2]->x.= pixiyii]->s) f-dpiz_y2l->y - pizcylil->y)-s 


line(1].0 = pix_y[i]->x - pix_y[1]->y * line[t].s; 
line[2].s =\<pisuy[2]->x = pix.y [0]=>x))/ (piz_y2]->y - pixyy[l0]=>y)s 
line[2].o = pix_y[0]->x - pix_y[0]->y * line[2].s; 


/* remove degenerate line */ 
if (pix_y[1]->y == pix_y[0]->y) { 
line[0] = line[1]; 
long_right = line[1].s > line[2].s; 
+ else if (pix_y[2]->y == pix_y[1]->y) f 
line[1] = line[0]; 
long_right = line[0].s < line[2].s; 
} else 
long_right = line[0].s < line[2].s; 


if (long_right) { /* arrange the lines */ 
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lef 
lef 


t [0] 
t[1] 


right [0] 
right [1] 


+ else { 
lef 
lef 


t [0] 
a 


right [0] 
right [1] 


/* 
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= &line[0]; 
= &line[1]; 
= &line[2]; 
= &line[2]; 


= &line[2]; 
= &line[2]; 
= &line[0]; 
= &line[1]; 


* pixel to barycentric coordinate transform. This is a 2D homogeneous 
* problem (to allow for translation) so the third component is set to 
* 1 and we have a 3-by-3 matrix equation. 


* / 
mi_matrix_ident(tmp1) ; 
tmpif 0] = pixa.x; 
tmpi{ 4] = pixb.x; 
tmpi[ 8] = pixc.x; 
tmpil 1] = pixa.y; 
tmpi[ 5] = pixb.y; 
tmpi[ 9] = pixc.y; 
tmpi[ 2] = 1.0f; 
tmpil 6] = 1.0f; 
tmpi[10] = 1.0f; 


mi_matrix_ident(tmp2); /* corresponds to barycentric vectors */ 
/* solve pix * pix_to_space = bary */ 
if (!mi_matrix_solve(pixel_to_bary, tmp1, tmp2, 4)) 


ret 


urn; 


/* compute geometric normal of the triangle */ 


mi_vector_sub(&d1, &b->point, &a->point) ; 
mi_vector_sub(&d2, &c->point, &a->point) ; 
mi_vector_prod(&state->normal_geom, &d1, &d2); 
mi_vector_normalize(&state->normal_geom) ; 


state->pri 


state->pri_ 


po = 2.08; 


idx 


pric /* set up primitive */ 
prigids; 


/* Loop over the texture y range */ 


y_min = ceil(pix_y[0]->y); 
if (y_min < 0) 
y_min = 


0; 


y_max = floor(pix_y[2]->y); 
if (y_min >= img->height) 
y_min = 


img->height-1; 


for (p.y=y_min; p.y <= y_max; p.yt++) f{ 
float 


int 


ieft.x, right _x; 
i= p.y © pizylil-ey 7 0 + i: 


/* Loop over texture X range */ 
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left_x = ceil(left[i]J->o + p.y*left[i]->s); 
if (left_x<0) 
left_x = 0; 


right_x = floor(right[i]->o + p.y*right[i]->s) ; 
if (right_x>=img->width) 
right_x = img->width-1; 


for (p.x=left_x; p.x <= right_x; p.x++) f{ 
miVector bary; 
miColor color; 


mi_vector_transform(&bary, &p, pixel_to_bary) ; 


/* constrain barycentric coordinates to triangle */ 
mib_lightmap_bary_fixup(&bary) ; 


/* pixel center is inside triangle */ 
mib_lightmap_combine_vectors(&state->point, 
&a->point, &b->point, &c->point, 
&bary) ; 
mib_lightmap_combine_vectors (&state->normal , 
&a->normal, &b->normal, &c->normal, 
&bary) ; 
mi_vector_normalize(&state->normal) ; 


/* get the color to write */ 
mi_call_shader_x(&color, miSHADER_MATERIAL, 
state, shader_tag, 0); 
/* write to the image */ 
mi_img_put_color(img, &color, (int)p.x, (int)p.y); 


* combine vectors using weights 


static void mib_lightmap_combine_vectors ( 


} 

} 

/* 

* / 
miVector 
miVector 


miVector 
miVector 
miVector 


res->x = 
resr>y = 
res->z = 


*res, 
const *a, 
const *b, 
const *c, 
const *bary) 


bary->x * a->x + bary->y * b->x + bary->z * c->x; 
bary->x * a->y + bary->y * b->y + bary->z * c—>y; 
bary->x * a->z + bary->y * b->z + bary->z! * c->z; 
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/* 
* Correct barycentric coordinates by projecting them to the 
* barycentric plane. The plane equation is (P-u)*n = 0, where 
* ?u’ is e.g. (1 00) and ’n’ is the plane normal (1 1 1). 
* We seek a scalar s so that 
* (B-sn-u)*n = 0 => s = ((u-B)*n) / (n*n) 
* and then add s*n to B. 
* 
* We then clip the barycentric coordinates and as a final touch, 
* compute z as a function of x and y since they are not independent. 
* This means that we can leave z out of the projection and 
* clipping phase 
* / 
static void mib_lightmap_bary_fixup( 
miVector *xbary ) 
. 
float S; 
s = (1.0f > bary->x + bary->9° > bary->z) /3.0f; 
bary->x += s; 
bary->y += s; 
/* now clip coordinates */ 
if (bary->x < 0.0£) 
bary->x = 0.0f; 
else if (bary->x > 1.0f) 
bary->x = 1.0f; 
if (bary->y < 0.0f) 
bary->y = 0.0f; 
else if (bary->y + bary->x > 1.0f) 
bary->y = 1.0f-bary->x; 
/* Finally, compute the dependent z */ 
bary->z = 1.0f - bary->x - bary->y; 
t 


If the lightmap shader wishes to cast rays, and apply proper jittering, mental ray 3.2 offers special 
jittering support. Suppose the shader needs to sample the lightmap texture raster coordinate p, it 
can derive a jittered raster coordinate p like this: 


if (state->options->jitter) { 
double jitter[2]; 
State->raster_x = p.x; 
state->raster_y = p.y; 
if (mi_query(143, state, 0, jitter)) { /* 143 is miQ_PIXEL_SAMPLE */ 
p.x += jitter([0]; 
p.y += jitter[1]; 
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This code fragment initializes QMC sequences and provides a jittered subpixel coordinate offset. 
It uses the miQ_PIXEL_SAMPLE mode of mi_query. Since this mode was introduced in mental ray 
3.2, the numeric equivalent 143 is used here to avoid compilation errors when this shader is 
compiled with an earlier mental ray version. Older mi_query versions will return false if mode 
143 is unsupported. 


As before, the complete sources can be downloaded from the mental images FTP server. 


Future support for on-demand lightmap generation will require changes to the way that the 
shader finds the writable texture (or writable user data) to write to; the tag will be stored in 
miRclm_mesh_render instead of being passed as a shader parameter. Shader writers should avoid 
writing more than one texture per lightmap shader to remain compatible with future versions of 
mental ray. 


3.24 Render Pass Merge Shaders: 


Multipass merge shaders combine multiple pass files to a single pass file or image. They have 
access to all pass files, but only a single sample location at a time. One of the input file may be 
the currently rendered scene instead of a pass file on disk; in this case the merge shader is called 
every time the renderer has completed one sample, such as when a lens shader or primary material 
shader returns. 


Here is an example of a simple merge shader that loops over all samples and selects the frontmost, 


based on its Z depth: 


DLLEXPORT int passmerge_version(void) {return(1) ;} 


DLLEXPORT miBoolean passmerge( 


miColor *dummy , 
miState *state, 
void *paras) 

+. 
int best_p = -1, p; 
miScalar best_z = 1e10, *zp; 
miColor *SIrc, *tar; 


for (pe0s; ptt) + 
zp = mi_renderpass_access(state, p, miRC_IMAGE_Z) ; 
if (!zp) break; 
if (*zp > 0 && *zp < best_z) { 
best_z = *zp; 


best_p = p; 
} 
} 
if (best_p >= 0) { 
tar = mi_renderpass_access(state, -1, miRC_IMAGE_RGBA) ; 


src = mi_renderpass_access(state, best_p, miRC_IMAGE_RGBA) ; 
*tar = *SYIC; 
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if ((int)state->raster_x/3/5 == (int)state->raster_y/37/5) 
switch(best_p) { 
case 0: tar->a = tar->r = 1; break; 
case 1: tar->a = tar->g = 1; break; 
case 2: tar->a = tar->b = 1; break; 
default: tar->a = tar->r = tar->g = tar->b = 1; 
¥ 
} 
return (miTRUE) ; 


The shader first loops over all passes, reading the Z distance from the depth frame buffer (miRC_ 
IMAGE_RGBA). In multipass rendering mode, the color and depth frame buffers always exist. When 
the lookup fails, the end of the pass list was reached and the loop terminates. Otherwise, for 
non-infinite depths («zp = 0), the one closest to the camera is saved in the best_ variables. 


When the closest sample was found, assuming one non-infinite distance was found, its color value 
is copied to the output (tar), and diagonal white stripes are painted on top. Only the color frame 
buffer is written to. A better merge shader would write the entire sample, and perform a correct 
depth-sorted alpha blending loop. This is what the built-in default merge function does. It is very 
rarely necessary to override the built-in merge function with a custom one like this. 


3.25 Render Pass Preprocessing Shaders: 


Multipass preprocessing shaders (prep shaders) access only a single pass file for reading and 
another for writing, but have access to all sample locations. Prep shaders are intended for 
“preparing” a pass file for later merging, by reading an existing pass file and writing a new 
one for later processing. For example, a prep shader may motion-blur on a subpixel sample level. 


Here is an example of a simple prep shader that replaces nonblank samples with a red-blue 
gradation: 

typedef struct {miColor color; miScalar depth;} Sample; 

DLLEXPORT int myprep_version(void) {return(1) ;} 


DLLEXPORT miBoolean myprep( 


miColor *dummy , 
miState *State, 
void *paras) 
{ 
int xl, yl, X8, YS, =res, yres, x, ¥;3 
Sample S; 


mi_renderpass_resolution(&xl, &yl, &xs, &ys, &xres, &yres, state, 0,0); 
mi_info("pos 4d %d, size %d %d, res 4d 4d", xl, yl, xs, ys, xres,yres); 
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for (y=0; y < yres; yt++) f 
for (x=0; x < xres; xt+) { 
if (!mi_renderpass_sample_get(&s, sizeof(s), state, 0, x, y)) f 
mi_error("%4d 74d: PREP READ ERROR", x, y); 


continue; 
} 
s.color.r = 1.0 * y / yres; 
s.color.b = 1.0 * x / xres; 
s.color.g = 0; 
s.color.a = 1; 


if (!mi_renderpass_sample_put(&s, sizeof(s), state, 0, x, y)) 
mi_error("%4d 74d: PREP WRITE ERROR", x, y); 
} 
if (!((y+1) % ys)) 
for (x=0; x < xrestxs-1; xt=xs) { 
mi_renderpass_samplerect_flush(state, 0, x, y - ysys); 
mi_renderpass_samplerect_flush(state, 1, x, y - ysys); 
} 
} 
return (miTRUE) ; 


The shader loops over all samples in order. Ordering is not required, and useful prep shaders will 
generally have some unordered access patterns, but performance and memory behavior improves 
if accesses, especially write accesses (mi_renderpass_sample_put) roughly work by rectangle. 
Rectangles are the rectangular raster space units that can be seen when attaching the zmf_disp 
viewer to a running mental ray. (Rectangles overlap.) Samples are stored in pass files in rectangle 


blocks. 


Normally mental ray will read and write entire rectangles, and keep them in memory until the 
prep shader returns. If the pass file is very large, this can require a lot of memory. The mz- 
renderpass_samplerect_flush function is available to remove rectangles from memory. It can be 
applied to the pass file being read (second argument is 0) and to the pass file being written (second 
argument is 1). Flushed read rectangles can be re-read, but flushed write rectangles can never be 
altered again. This is why prep shaders should prefer ordering their write accesses over ordering 
their read accesses. 


3.26 Functions for Shaders 


mental ray makes a range of functions available to shaders that can be used to access data, cast 
rays, looking up images, and perform standard mathematical computations. The functions are 
grouped by the module that supplies them. The shader writer may also use C library functions, 
but it is mandatory to include <stdio.h> and <math.h> if printing functions such as fprintf 
(use mi_info or similar for console debugging messages) or math functions such as sin are used. 
Not including these headers may abort rendering at runtime, even though the compiler did not 
complain. All shaders must include the standard mental ray header file, shader -h. 
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Here is a summary of functions provided by mental ray. Section 3.26.20 shows which functions 
can be used in which shaders. 


Shader Calls 


miBoolean mi_call_shader *result, type, *state, tag 
miBoolean mi_call_shader_x *result, type, *state, tag, *arg 
miBoolean mi_call_material *result, *state 

miBoolean mi_call_photon_material *result, *state 

miBoolean mi_call_shadow_material>* *result, *state 

miBoolean mi-_call_environment_material>? *result, *state 

miBoolean mi_call_volume_material>* *result, *state 

miBoolean mi-call_photonvol_materia *result, *state 

miBoolean mi_call_contour_material> *result, “void, *void, *state 
void * mi_eval *state, *param 

miBoolean * mi_eval_boolean *param 

muilnteger * mi_eval_integer *param 

miScalar * mi_eval_scalar *param 

miVector * mi_eval_vector *param 

miScalar * mi_eval_transform *param 

miColor * mi_eval_color *param 

milag * mi_eval_tag *param 

void mi_flush_cache * state 


]3-3 


mi_db_type 
mi_db_size 
mi_db_access 
mi_db_unpin 


mi_db_flush 
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RC Functions 


miBoolean mi_trace_eye *result, *state, *org, *dir 


miBoolean mi_trace_reflection *result, *state, *dir 
miBoolean mi_trace_refraction *result, *state, *dir 
miBoolean mi_trace_transparent *result, *state 
miBoolean mi_trace_environment *result, *state, *dir 
miBoolean mi-_trace_probe *state, *dir, “org 
miBoolean mi_trace_transparent *result, *state 
miBoolean mi_trace_continue>”> *result, *state 
miBoolean mi-_trace_light *resiwit. tdi nl: *st, 1 
miBoolean mi_sample_light *result, *dir, *nl, *st,*s 
miBoolean mi_trace_shadow *result, *state 
miBoolean mi_trace_shadow_seg *result, *state 
miBoolean mi_continue_shadow-seg** *result, *state 
miBoolean mi_ray_offset? *state, *offset 
miBoolean mi_ray_falloff?? *state, ‘start, *stop 
miBoolean mi_inclusive_lightlist *n, **hights, *state 
miBoolean mi_exclusive_lightlist +n, **hiehts, *state 
miScalar mi_lightprofile_value*:! *prof, phi, theta, *pos, rel 
miScalar mi_lightprofile_sample?:! *state, proftag, rel 
miBoolean mi_compute-_irradiance *result, *state 
miBoolean mi_compute-_irradiance_backside?* *result, *state 
miBoolean mi_compute_avg_radiance?” *result, *state, face, irrad_options 
miBoolean mi_compute_volume irradiance *result, *state 
miBoolean mi_compute-directional_irradiance *result, *state, r, g1, g2 
miBoolean mi_finalgather_store** *result, *state, mode 


miBoolean mi_sample *sample, *i, *state, dim, *n 


RC Photon Functions 


miBoolean mi_photon_light “energy, 


miBoolean mi_photon_reflection_specular *energy, *state, *dir 
miBoolean mi_photon-_reflection_glossy *energy, “state, *dir 
miBoolean mi_photon_reflection_diffuse *energy, ‘state, *dir 
miBoolean mi_photon_transmission_specular *energy, ‘state, *dir 
miBoolean mi_photon_transmission_glossy *energy, *state, *dir 
miBoolean mi_photon_transmission_diffuse *energy, *state, *dir 
miBoolean mi_photon-_transparent “energy, *state 

miBoolean mi_photon_volume-scattering *energy, “state, *dir 
void mi_store_photon *energy, “state 


void mi_store_volume_photon *energy, 
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RC Direction Functions 
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void 
void 
void 
void 


void 
miBoolean 


miBoolean 
miBoolean 
miBoolean 


void 
void 
void 
miScalar 


mi_reflection_dir 
mi_reflection_dir_specular 
mi_reflection_dir_glossy 
mi_reflection_dir_anisglossy 
mi_reflection_dir_diffuse 
mi_refraction_dir 
mi_transmission_dir_specular 
mi_transmission_dir_glossy 
mi_transmission_dir_anisglossy 


mi_transmission_dir_diffuse 
mi-scattering_dir_diffuse 
mi_scattering_dir_directional 
mi-scattering_pathlength 


Vector and Matrix Math Functions 


dir, state 

*dir, *state 

*dir, *state, shiny 

*dir, *state, u, v, shiny_u, shiny_v 
*dir, *state 

dir, state, ior_in, 1or_out 

*dir. *state; *in, *out 

*dir, *state, *in, *out, shiny 

*dir, *state, *in, *out, u, v, shiny_u, 
shiny_v 

*dir, *state 

*dir, *state 

*dir, *state, directionality 

*state, density 


void 
void 
void 
void 
void 
void 
miScalar 
miScalar 
void 
void 
void 
miScalar 
miScalar 
void 
void 
miBoolean 
void 
miBoolean 
void 
void 
void 
void 
void 


mi_vector_neg 
mi_vector_add 
mi_vector_sub 
mi_vector_mul 
mi_vector_div 
mi_vector_prod 
mi_vector_dot 
mi_vector_norm 
mi_vector_normalize 
mi_vector_min 
mi_vector_max 
mi_vector_det 
mi_vector_dist 
mi_matrix_null 
mi_matrix_ident 
mi_matrix_isident 
mi_matrix_copy 
mi_matrix_invert 
mi_matrix_prod 
mi_matrix_rot_det 
mi_matrix_rotate 
mi_matrix_rotate_axis 
mi_matrix_solve’* 
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Transformation Math Functions 


id mi_point_transform ss 
mi_vector_transform 
mi_vector_transform_T 
mi_point_to_world 
mi_point_to_camera 
mi_point_to_object 
mi_point_to_light 
mi_point_to_raster 
mi_point_from_world 
mi_point_from_camera 
mi_point_from_object 
mi_point_from_light 
mi_vector_to_world 
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— “ 


as 
“- 


mi_vector_to_camera 


as 
“> 


mi_vector_to_object 
mi_vector_to_light 
mi_vector_from_world 
mi_vector_from_camera 
mi_vector_from_object 
mi_vector_from_light 
mi_normal_to_world 
mi_normal_to_camera 
mi_normal_to_object 
mi_normal_to_light 
mi_normal_from_world 
mi_normal_from_camera 
mi_normal_from_object 
mi_normal_from_light 
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Noise Functions 


miScalar 
miScalar 
miScalar 
double 

miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 
miScalar 


IMG Functions 


void mi_img_put_color *image, *color, x, y 
void mi_img_get_color *image, *color, x, y 
void mi_img_put-scalar *image, scalar, x, y 
void mi_img_get_scalar *image, *scalar, x, y 
void mi_img_put_vector *image, “vector, xX, y 
void mi_img_get_vector *image, *vector, x, y 
void mi_img_put_depth *image, depth, x, y 
void mi_img_get_depth *image, *depth, x, y 
void mi_img_put_normal *image, *normal, x, y 
void mi_img_get_normal *image, *normal, x, y 
void mi_img_put_label *image, label, x, y 
void mi_img_get_label *image, “label, x, y 


miBoolean 


mi_random 
mi-_srandom 
mi_erandom 
mi_par_random 
mi-_spline 
mi_noise_Id 
mi_noise_2d 
mi_noise_3d 
mi-_noise_1d_grad 
mi_noise_2d_grad 
mi_noise_3d_grad 
mi_unoise_1d 
mi_unoise_2d 
mi_unoise_3d 
mi_unoise_1d_grad 
mi_unoise_2d_grad 
mi_unoise_3d_grad 


mi_img_tonemap *outimage, *inimage, *paras 
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Color Profile Functions 


miUintl mi_colorprofile_renderspace_id 


miUintl mi_colorprofile_internalspace_id 
miUintl mi_colorprofile_ciexyz_id 
miBoolean mi_colorprofile_internal_to_render 
miBoolean mi_colorprofile_internal_to_ciexyz 
miBoolean mi_colorprofile_render_to_internal 
miBoolean mi_colorprofile_render_to_ciexyz 
miBoolean mi-_colorprofile_ciexyz_to_render 
miBoolean mi_colorprofile_ciexyz_to_internal 


Shading Models 


miScalar mi_fresnel ni, n2, tiate 

miScalar mi_fresnel_reflection * state, “1, *o 

miScalar mi_phong_specular spec, “state, *dir 

void mi_tresnel_specular ae. * es. S. * et, 
*dir, *in, *out 

miScalar mi_blinn_specular spec, *state, *dir 

miScalar mi_blong-_specular spec, *state, *dir 

miBoolean mi_cooktorr_specular *result, *di, *dr, *n, roughness, *ior 

miScalar mi_ward_glossy *di, *dr, *n, shiny 

miScalar mi_ward_anisglossy *di, *dr, *n, *u, *v, shiny_u, shiny_ 
Vv 

miScalar mi-_schlick_scatter *di, *dr, directionality 

miRay_type mi_choose_scatter_type *state, transp, *specular, *glossy, 
* diffuse 

miRay-_type mi_choose_simple-_scatter_type *state, *rdiff, *rspec, *tdiff, *tspec 

milnteger mi_choose_lobe * state, f 
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Auxiliary Functions 


miBoolean 
miBoolean 
miBoolean 
miBoolean 
miBoolean 
miBoolean 
miScalar 
miBoolean 
miBoolean 
miBoolean 
miBoolean 
miBoolean 
miBoolean 
void * 


mi_lookup-color_texture 
mi_lookup-scalar_texture 
mi_lookup_vector_texture 


mi_lookup_filter_color_texture 


mi_texture_filter_project 
mi_texture_filter_transform 
mi_luminance 
mi_tri_vectors 
mi_texture_interpolate** 
mi_raster_unit?? 

mi_query 


mi_shaderstate_enumerate”’ 


mi_shaderstate_set?* 
mi_shaderstate_get?? 


*col, *state, tag, *v 
teeal "stare, tae, FV 

"yee, "state; tag, “Vv 

*col, *state, tag, *paras, ST 
p[3], t[3], *state, disc_r, space 
ST, p[3], t[3] 

*state, color 

*state. wh, tit, **4, **b, **> 
*state, space, *result 

“state, "x, *y 

query, *state, tag, *result, ... 
*state, *cb, *arg 

*state, *key, ks, *val, vs, t 
*state, *key, ks, *vs 


miBoolean mi_tb_put *state, fb, *data 
miBoolean mi_tb_get *state, fb, *data 
milmg_image | *state, idx 

* mi_output_ 

image_open>* 

void mi_output_image_close>* * state, idx 

miBoolean mi_geoshader_add_result query, *state, tag, *resullt, ... 
miBoolean mi_geoshader-tesselate *state, *leaves, source 
miBoolean mi_geoshader-_tesselate_end leaves 

miBoolean mi_geoshader_echo_tag?* *fp, tag, *eopt 

char:* mi-_string_substitute *new, *old, size 
milnteger mi_volume_num-_shaders?* *state 

milnteger mi_volume_cur_shader** *state 

miColor * mi_volume-_tags>* *state 

milag * mi_volume-_user-_color?* *state 


void 
miBoolean 


t 
te 


mi_opacity-se 
mi_opacity_ge 


*state, *color 
*state, *color 
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Multipass Rendering Functions 


These functions are available only to pass merge (access) or pass preprocessing (get, put, flush, 


black) shaders. 


void * mi_renderpass_access”: *state, pass, db 
miBoolean mi_renderpass_sample_get>'! *result, sz, *state, fb, x, y 
miBoolean mi_renderpass_sample_put?' *result, sz, *state, fb, x, y 
miBoolean mi_renderpass_samplerect_flush>:! *result, *state, x, y 
miBoolean mi_renderpass_samplerect_black>* *result, *state, x, y 


Obsolete Auxiliary Functions 


These functions are obsolete; use mzi_query for future implementations. 


mi_light_info tag, *org, *dir, **paras 
mi_global_lights_info ** tag 


id 


mi_texture_info tag, Axres,." yes, ** paras 
mi_shader_info *state 
mi_instance_info "state. *“parae. *ol, "n2. pe 


Contour Functions 


miBoolean mi-_get_contour_line *y1. "2 
void mi_add_contour_lines p1{], p2[], n 


Light Mapping Functions 


milmg-image* | mi_lightmap-edit’: **handle, tag 
void mi_lightmap_edit_end?* *handle 
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Memory Allocation 


qd 


mi_mem_allocate Size 
mi_mem_reallocate mem, size 


mi_mem_release mem 
mi_mem_check 

mi_mem_dump mod 
mi_mem_strdup *text 


Thread Parallelism and Locks 


d 


mi_init_lock *lock 
mi_delete_lock *lock 
mi_lock lock 
mi_unlock lock 
mi_par_localvpu?' 

mi_par_nthreads7'! 

mi_par_aborted 


Messages and Errors 


af. 


mi_fatal *messape, «.. 
mi_error *message, ... 
mi_warning *message, ... 


mi_info * message, ... 
mi_progress * message, ... 
mi_debug *message, ... 
mi_vdebug *messaye, ‘. 


Shader Calls 


Shaders can be called either explicitly, or implicitly by evaluating a shader parameter that may be 
assigned to the output of another shader. 


miBoolean mi_call_shader ( 
miColor * const result, 
miShader_type type, 
miState * const state, 
miTag shader) 
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miBoolean mi_call_shader_x( 
miColor * const result, 
miShader_type type, 
miState * const state, 
miTag shader, 
void *arg) 


These functions call the shader specified by the tag shader. The extended version passes the arg 
parameter as a fourth argument to the shader. The other version passes a null pointer as fourth 
argument to the shader. mz_call_shader_x is slightly more efficient than mz_call_shader. 


The tag is normally a texture shader or light shader or some other type of shader found in the 
calling shader’s parameter list. The caller must pass its own state and the shader type, which must 
be one of miSHADER_LENS, miSHADER_MATERIAL, miSHADER_LIGHT, miSHADER_SHADOW miSHADER_ 
ENVIRONMENT miSHADER_VOLUME, and miSHADER_TEXTURE. The sequence of operations is: 


1. shader is written into state — shader. 


2. If the called shader is dynamically loaded and has an init shader that has not been called 
yet, it is called now, with state as its only argument. 


3. The shader referenced by shader is called with three arguments: the resu/t pointer, the given 
state, and the shader parameters retrieved from shader. 


4. After the shader returns, state — shader is restored to its old value. 


The return value of the shader is returned. If the shader expects a result argument of a type other 
than miColor, the pointer must be cast to miColor when passed to mi_call_shader. Note that 
the shader tag references an entire function call including shader parameters as defined in the 
.mi file with a texture, light, or some other statement combining shading function and shader 
parameters; shader is not just a simple pointer or reference to a C function. 


miBoolean mi_call_material ( 
miColor *result, 
miState *state) ; 


Call the material shader in state — material. This works both for standard materials and 
Phenomenon materials. 


miBoolean mi_call_photon_material ( 
miColor *result, 
miState *state) ; 


Call the photon shader in state — material. This works both for standard materials and 
Phenomenon materials. It calls the photon shader of a material Phenomenon. 
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miBoolean mi_call_shadow_material ( 
miColor *result, 
miState *State) ; 


3-3 Call the shadow shader in state — material. This works both for standard materials and 
Phenomenon materials. It calls the shadow shader of a material Phenomenon. 


miBoolean mi_call_environment_material ( 
miColor *result, 
miState *state) ; 


3-3 Call the environment shader in state — material. This works both for standard materials and 
Phenomenon materials. It calls the environment shader of a material Phenomenon. 


miBoolean mi_call_volume_material ( 
miColor *result, 
miState *state) ; 


3-3 Call the volume shader in state — material. This works both for standard materials and 
Phenomenon materials. It calls the volume shader of a material Phenomenon. 


miBoolean mi_call_photonvol_material ( 
miColor *result, 
miState *state) ; 


>> Call the photonvol shader in state — material. This works both for standard materials and 
Phenomenon materials. It calls the photonvol shader of a material Phenomenon. 


miBoolean mi_call_contour_material ( 
miContour_endpoint *result, 


void *info_near, 
void *info_far, 
miState *state) ; 


°-* Call the contour shader in state — material. This works both for standard materials and 
Phenomenon materials. It calls the contour shader of a material Phenomenon. mi_call_contour- 
material may only be called in contour mode, with a contour shader as parent of a shade tree. 
info_near and info_far must be passed from a parent contour shader. The contour contrast shader, 
the contour storage shader, and the contour shader itself must use matching info_near and info_ 
far values. The info structures must have the same size and layout. 
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void *mi_eval ( 
mistate *State, 
void *param ) 


miBoolean *mi_eval_boolean ( 
miBoolean *param ) 


miInteger *mi_eval_integer ( 
miInteger *param) 


miScalar *mi_eval_scalar( 
miScalar *param ) 


miVector *mi_eval_vector ( 
miVector *param) 


miScalar *mi_eval_transform( 
miScalar *param ) 


miColor *mi_eval_color( 
miColor *param ) 


miTag *mi_eval_tag( 
miTag *param ) 


Return the value of a shader parameter. If the shader parameter value is a constant, mi_eval returns 
its argument. If the parameter is assigned to another shader, call that shader and return a pointer 
to its return value (or the cached return value if it has been called recently). If the parameter is 
assigned to a Phenomenon interface, return a pointer to the value in the interface. The latter two 
cases let shaders operate in the contexts of shader assignments and phenomena without needing 
knowledge of the context, which is automatically handled. The pointer remains valid until the 
shader returns, which avoids the need to copy a large returned data structure such as a color 
or array to temporary variables. Shaders should always access their parameters with mz_eval. It 
parameters are accessed without mi_eval and the parameter is assigned to another shader or an 
interface, the shader will see garbage. 


The typed variants of mi_eval are implemented as macros for the convenience of shader writers. 
They cast their argument to a void pointer, call mz_eval, and recast the returned pointer to the 
appropriate type. They all make the assumption that the shader has a local variable state of 
type miState * in scope. Experience has shown that the typed variants make source code look 
much cleaner. Note that there is only one macro mi_eval_tag that can be used for parameters of 
type shader, color texture, vector texture, scalar texture, light, material, and geometry. All typed 
variants have been designed to return the same type they accept as an argument. 


Always use the correct simple type. For example, if the parameter has type color, it must be 
evaluated as a single color (probably using mi_eval_color). It is not possible to use four scalar 
evaluations to access the R, G, B, and A components separately. Also, by convention, arrays 
should be evaluated as a unit, evaluating two integers for the i_ index, the n_ member count, and 


320 3 Using and Writing Shaders 


the array itself. However, structures are not evaluated as a unit; a separate evaluation is necessary 
for every simple member it contains. 


void mi_flush_cache( 
miState *State) 


Prevents the cache from being used by future calls to mi_eval. If mi_eval calls another shader, 
the result is stored in a special cache in that other shader, which is normally flushed only when 
the entire shader graph returns. This means that the other shader will only ever be called once 
during the evaluation of a shader graph, and all m_evals are satisfied from the cache. Notice that 
flushing applies to the entire sub-graph of shaders evaluated by this and future mi_evals; there is 
no way to flush the cache of a single shader because that would leave its sub-shaders in a funny 
state. The result cache is still active for shaders which call mi_flush_cache. 


This is useful if the code calls a another shader more than once, such as a texture shader to sample 
a texture at three different locations to compute bump mapping gradients. Although the shader, 
if called with mi_call_shader or mi_lookup-color_texture, will get called each time, its sub-shaders 
inside the same Phenomenon will not if these subshaders are called as the result of mi_eval. 
(Remember that m_eval results are cached.) However, if mi_flush_cache is used before the second 
and every subsequent shader call, the called shader’s mi_eval calls will cause a fresh subshader 
call. 


3.26.1 DB Functions 


Database access functions can be used to convert pointers into tags, and to get the type of a tag. 
The scene database contains only tags and no pointers at all, because pointers are not valid on 
other machines. A tag is a 32-bit integer value that uniquely identifies a piece of data in mental 
ray’s virtual shared database. It acts like a pointer except that it is valid across all machines on the 
network. 


int mi_db_type( 
const miTag tag) 


Return the type of a database item. The tag must exist. Valid types that are of interest in shaders 
are: 


miSCENE_FUNCTION ~— Function to call, such as a shading function 
miSCENE_MATERIAL Material containing shaders and flags 
miSCENE_LIGHT Light source 

miSCENE_IMAGE Image in memory 


The most important are functions and images, because general-purpose texture shaders need to 
distinguish procedural and image textures. See the texture shader example on page 245. 
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int mi_db_size( 
const miTag tag) 


Return the size of a database item in bytes. The tag must exist. This function should be avoided 
if possible because it has poor performance and can lead to inefficient execution orders in mental 
ray 3.0 in certain situations. 


void *mi_db_access( 
const miTag tag) 


Look up the tag in the database, pin it, and return a pointer to the referenced item. Pinning means 
that the database item is guaranteed to stay in memory at the same location until the item is 
explicitly unpinned. Rendering aborts if the given tag does not exist. mi_db_access always returns 
a valid pointer. If an item is accessed twice, it must be unpinned twice; pinned is a counter, not a 
flag. The maximum number of simultaneous pins on a single database element is 65535. 


void mi_db_unpin( 
const miTag tag) 


Every tag that was accessed with mi_db_access must be unpinned with this function when the 
pointer is no longer needed. Failure to unpin can cause a pin overflow, which may abort rendering. 
After unpinning, the pointer may not be used any more. 


void mi_db_flush( 
const miTag tag) 


This call is obsolete. It made the assumption that mi_db_access could be used for writing to data. 
This is no longer true. Do not use mi_db_flush. 


3.26.2 RC Functions 


These are the functions supplied by the render modules of mental ray, RC*. All following trace 
functions return miTRUE if any subsequent call of a shader returned miTRUE to indicate presence 
of illumination. Otherwise no illumination is present and miFALSE is returned. All trace functions 
derive the state of the ray to be cast from the given state of the parent ray. This state becomes 
the “child state” that is passed to subsequent shaders that are called by the trace function. The 
state is always copied, and the given state is not modified except for the state fields label, point, 
normal, dist and motion. These fields are copied from the child state so that the lens shader can 
access them in the state modified by mz_trace_eye. After the trace function returns, the caller may 
examine the child state (but not the grandchild, which is gone if it ever existed). Volume shaders 
get the same state as the previous (material) shader. Note that all point and direction vectors 
passed as arguments to tracing functions must be in internal space. 
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miBoolean mi_trace_eye( 


miColor *result, 
miState *State, 
miVector *origin, 
miVector *direction) 


casts an eye ray from origin in direction, or calls the next lens shader. The allowed origin 
and direction values are restricted when using the ray classification?! rendering algorithm (not 
recommended, it exists only for backwards compatibility). If scanline rendering is turned on and 
state—scanline is not zero, origin and direction must be the same as in the initial call of mz_trace- 
eye, and the lens shader may not modify them. Lens shaders that depend on modifying ray origin 
and direction should be declared with the trace on option. Origin and direction must be given 
in internal space. This function may be used only in lens shaders. Note that mi_trace_eye stores 
origin and direction in state — org and state — dir, respectively, overwriting the previous values. 


miBoolean mi_trace_reflection( 


miColor *result, 
miState *state, 
miVector *direction) 


casts a reflection ray from state—point to direction. It returns miFALSE if the trace depth has been 
exhausted or, in mental ray 3.4 and higher, if the hit object has disabled reflection receiving. If no 
intersection is found, the optional environment shader is called. The direction must be given in 
internal space. This function may be used only in shaders called during image rendering, but not 
in displacement, geometry, photon, or output shaders. 


miBoolean mi_trace_refraction( 


miColor *result, 
miState *State, 
miVector *direction) 


casts a refraction ray from state—point to direction. It returns miFALSE if the trace depth has been 
exhausted or, in mental ray 3.4 and higher, if the hit object has disabled refraction receiving. If no 
intersection is found, the optional environment shader is called. Before this functions casts the 
refraction ray, after copying the state, it copies state—refraction_volume to state—volume because 
the ray is now assumed to be “inside” the object, so the volume shader that describes the inside 
should be used to modify the ray while traveling inside the object. It is the caller’s responsibility 
to set state—refraction_volume to the camera’s volume shader state—camera—volume or some 
other volume shader if it determines that the ray is now leaving the object. The direction must be 
given in internal space. 


If ray tracing has been disabled, mi_trace_refraction cannot modify the ray direction and operates 
like mi_trace_transparent. This function may be used only in shaders called during image 
rendering, but not in displacement, geometry, photon, or output shaders. 
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miBoolean mi_trace_transparent ( 
miColor *result, 
miState *kstate) 


does the same as mi_trace_refraction with dir == state—-dir (that is, no change in the ray direction) 
but may be executed faster if the parent ray is an eye ray. It also works when ray tracing is turned 
off, and in mental ray 3.2, considers visible as well as trace objects. If the ray direction does 
not change (because no index of refraction or similar modification is applied), it is more efficient 
to cast a transparency ray than a refraction ray. Like mi_trace_refraction, this function copies 
the refraction volume shader to the volume shader because the ray is now assumed to be inside 
the object. This function may be used only in shaders called during image rendering, but not 
in displacement, geometry, photon, or output shaders. In mental ray 3.4 this function returns 
miFALSE and a transparent black color if the hit object has disabled transparency receiving. 

In rasterizer?? mode (formerly called Rapid Motion), mi_trace_transparent always returns 
miFALSE and a transparent black color if no ray has been traced yet. Since the rasterizer separates 
shading from compositing, there is no object “behind” the current surface at the time the material 
shader is called. The object “behind” will be shaded at some other time, and both results are 
composited long after the material shaders have returned. As long as the shader uses standard 
linear composition for mi_trace_transparent results, returning black gives exactly the same result 
regardless of whether rasterizer mode is in effect or not, the composition just happens later. 
However, if the shader performs nonstandard compositing, or evaluates environments if mz- 
trace_transparent returns false, it must be modified to work properly in rasterizer mode. A 
shader can detect rasterizer mode by testing whether state — scanline == 'r’. 


miBoolean mi_trace_continue ( 
miColor * const result, 
miState * const state) 


>> continues the current ray, in the same direction. Unlike other trace calls, state — origin is not 


set to state — point but remains unchanged, state — type remains unchanged, and no new state 
is created. There are no trace depth checks. Effectively, this call pretends to the next intersection 
that the current intersection never happened, although the shader that calls mi_trace_continue 
does have the option to manipulate the state and returned color. Care should be taken because the 
state is not copied, so the next intersection will have operated on state instead of state — child. 
state — child is left undefined. This function can be used to control object visibility based on 
more complex criteria than the object vzszble flag. 


Unlike mi_trace_transparent, which will ignore the intersections happening very close to the origin 
of the transparency ray, mi_trace_continue guarantees that if there is another triangle coplanar 
to the hit triangle, then the other triangle will also be hit. The order with which the multiple 
coplanar triangles are hit is undefined. 


miBoolean mi_trace_environment ( 
miColor *result, 
miState *state, 
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miVector *direction) 


casts a ray into the environment. The trace depth is not incremented or checked. The environment 
shader in the state is called to compute the color to be returned. The direction must be given in 
internal space. 


miBoolean mi_trace_probe( 


miState *State, 
miVector *direction, 
miVector *org) 


casts a ray into the scene, starting at org with the direction direction, both in internal space 
coordinates. If nothing is hit, miFALSE is returned. If the ray hits another object, miTRUE is 
returned and state — child is set to the state that the material shader of the hit object would 
have seen. However, unlike all other mi_trace_* functions, no shader is called. Note that the state 
state — child does not itself have a state, so it cannot be used to call a material shader at the hit 
object directly. This requires setting up an artificial “grandchild” state: 


if (mi_trace_probe(state, &dir, korg)) { 
miState grandchild; 
Sstate->child->child = &grandchild; 
if (mi_call_material(&result, state->child)) 
/* use the result */ 


This sequence works roughly like mi_trace_reflection, except that no ray levels are tested, no 
environment is sampled, and no volume shaders are called. Note that m_trace_probe will always 
return miFALSE if ray tracing is disabled. Also note that mental ray 3.1 finds objects regardless of 
flags, while mental ray 3.2 finds only objects that have the trace flag set. 


If the start point org of the probe ray is different from state — point, state — pri should be set 
to 0, and restored after mi_trace_probe returns. state — pri is used to prevent self-intersections, 
which is not useful if the start point is not state — point and/or the probe ray begins in empty 
space. 


Until mental ray 3.2, a probe ray can hit all onbjects, but beginning with mental ray 3.2 it sees 
only objects that have the trace flag set. The reason for this is that visible-only objects no longer 
need to be put into the ray tracing acceleration structures (like the BSP tree), which supports the 
model of separating high-resolution visible geometry from low-resolution trace geometry. This 
model is also supported by approximation flags’? and ray offsets*?. 


miBoolean mi_sample_light ( 
miColor *result, 
miVector *dir, 
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miScalar *dot_nl, 
misState *State, 
miTag light_inst, 
miInteger *samples) 


casts a light ray from the light source to the intersection point, causing the light source’s light 
shader to be called. The light shader may then calculate shadows by casting a shadow ray to the 
intersection point. This may cause shadow shaders of occluding objects to be called, and will also 
cause the volume shader of the state to be called, if there is one. Before the light is sampled, the 
direction from the current intersection point in the state to the light and the dot product of this 
direction and the normal in the state are calculated and returned in dir and dot_nl if these pointers 
are nonzero. The direction is returned in internal space. The light instance to sample must be 
given in light_inst. samples must point to an integer that is initialized to 0. mi_sample_light must 
be called in a loop until it returns miFALSE. *samples will then contain the total number of light 
samples taken; it may be larger than 1 for area light sources. 


For every call in the loop, a different dir and dot_nl is returned because the rays go to different 
points on the area light source. The caller is expected to use these variables, the returned color, and 
other variables such as diffuse and specular colors from the shader parameters to compute a color. 
These colors are accumulated until mi_sample_light returns miFALSE and the loop terminates’. 
The caller then divides the accumulated color by the number of samples (*samples) if it is greater 
than 0, effectively averaging all the intermediate results. See page 234 for an example of a shader 


using mi_sample_light. 


When casting light rays with mi_sample_tlight, mental ray may check whether the primitive’s 
normal is pointing away from the light and ignore the light in this case. For this reason some 
shaders, such as ray marching volume shaders, should assign 0 to state—pri first, and restore it 
before returning. All mi_qguery modes that return information on the intersected surface, such as 
miQ_PRI_BBOX_MIN/MAX, miQ_NUM_TEXTURES, miQ_GEO_LABEL, and miQ_GEO_DATA, do not work if 
prt has been modified. In mental ray 3.1.2 or later, shaders that operate on a surface such as material 
shaders may clear state — normal instead, which disables the backside light test but preserves 
the information on the current surface for mi_query and self-shadowing tests. (state — pri is an 
identifier for the intersected “primitive” of the surface.) 


Light instance tags to call this function with can be found either in shader parameters of type 
light or array light, or in the global light list obtained from mi_query. 


This function works with light groups introduced in mental ray 3.3. 


miBoolean mi_trace_light ( 


miColor *result, 
miVector *dir, 
miScalar *dot_nl, 
misState *State, 
miTag light_inst) 


*mental ray 3.3 and later leave dir and dot_nl undefined when returning miFALSE. Previous versions set it to 0.0. 
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is a simpler variation of mi_sample_light that does not keep a sample counter, and is not called in 
a loop. It is equivalent to mi_sample_light except for area light sources. Area light sources must 
be sampled multiple times with different directions, which is not supported accurately by this 
function because it can only return a single direction and dot_n/. This function is provided for 
backwards compatibility with mental ray 1.9 only, do not use it for new projects. 


miBoolean mi_trace_shadow( 
miColor * const result, 
miState * const state) 


computes shadows for the given light ray by casting shadow rays. This function is normally called 
from a light shader to take occluding objects that prevent some or all of the light emitted by the 
light source to reach the illuminated point (whose material shader has probably called the light 
shader). The result color is modified by the shadow shaders that are called if occluding objects 
are found. Note that light shaders can improve performance by tracing shadow rays only if the 
contribution from the light is greater than some threshold, for example because distance or angle 
attenuation has left so little of the light color (less than 1/256, for example) that applying shadow 
occlusion to this value is not going to make any difference. This function returns miFALSE if full 
occlusion is detected, that is, resu/t is black or, in mental ray 3.4 and higher, if the hit object has 
shadow receiving disabled. 


miBoolean mi_trace_shadow_seg ( 
miColor * const result, 
miState * const state) 


recursively calls the shadow shader for the next shadow segment and returns its result, or the 
result of the light shader if there is no more shadow intersection. It does nothing if shadow 
segments are turned off. It is used by shadow shaders only; light shaders always use mi_trace- 
shadow. See the introduction to shader types and the shadow shader explanation for details on 
shadow modes. This function returns miFALSE if full occlusion is detected, that is, resu/t is black. 


miBoolean mi_continue_shadow_seg ( 
miColor * const result, 
miState * const state) 


°-* allows a shadow shader to continue tracing the exact same shadow segment that triggered this 
shadow shader, thus effectively ignoring the corresponding occluder. In other words, it allows to 
ignore occluders on a per shadow segment basis. The next shadow shader wiill be called as if the 
previous intersection never existed. mi_continue_shadow-seg leaves the state unchanged from the 
perspective of the next shadow shader. Like m1_trace_shadow-seg, this function must be called by 
shadow shaders only. It returns miFALSE if full occlusion is detected, that is, reswJt is black. 


miBoolean mi_ray_offset ( 
miState *State, 
double *offset) 
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° All rays cast from this point on will begin a little distance away from state — point, defined 
by *offset. Objects closer than this distance will not be hit by the ray. This is useful if there are 
low-resolution shadow or trace standins (possibly created by approximation flags) that are some 
distance away: if the rays ignore very nearby other objects, they cannot hit the low-resolution 
version, which avoids self-shadowing or self-reflection, especially self-reflection caused by final 
gathering. The old “offset value is returned, and should be restored before the shader returns; it 
should be used to bracket functions like mi_trace_reflection or mi_compute irradiance. 


miBoolean mi_ray_falloff ( 
miState *State, 
double *Start, 
double *Stop) 


>? All rays and photons cast within this shader call from now on will reach a maximum distance 
of *stop, measured from state — point when the ray or photon tracing function or mi_compute- 
irradiance is called. The maximum distance is applied to every single ray or photon segment; 
lengths are not accumulated. Objects farther away will not be hit; instead, the environment will 
be returned (unless cleared in the state by the shader). The *start parameter defines a falloff 
distance; objects at a distance between *start and *stop will fade from the object color to the 
environment color (or black if none), to avoid hard edges in animations. This function is useful 
to limit the reach of rays, especially finalgather rays, to keep computation local and not fill 
the geometry cache with distant objects that do not matter much anyway. The old start and 
stop values are returned, and should be restored before the shader returns. This function takes 
precedence over falloffs in the options and objects. 


miBoolean mi_inclusive_lightlist ( 
int *n_lights, 
miTag **klights, 
miState *state) 


This function accepts a list of light source instances, and returns a modified list that includes all 
other instances of the instanced lights as well. If a light is instanced three times in the scene, and 
one (or more) of them appears in */ights, then */ights will contain all three after this call. n_lights 
points to an integer containing the original list size, and lights points to a pointer to the original 
list. After the function returns, the integer holds the new list length, and the pointer points to a 
new list. Both the integer and the pointer should be on the stack and should be initialized from 
the shader parameters using mi_eval to avoid overwriting the actual shader parameters, which 
should remain intact for the next shader call. The returned list should not be written to by the 


shader. 


The new list is a copy of the global light list (see 71_qguery) with only those lights that match the 
passed original list included. The returned list remains valid until the next call to mi_inclusive- 
lightlist or mt_exclusive_lightlist. Note that this function involves a loop over all lights, and may 
be a good candidate for calling once in the init shader instead of once every time the shader is 
called, if */ights is known to be constant during the frame. 
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This function works with light groups introduced in mental ray 3.3. 


miBoolean mi_exclusive_lightlist ( 
int *n_lights, 
miTag **klights, 
miState *state) 


This function is similar to the previous, but returns all global light instances except those whose 
instanced light match a light instanced in the given list. Both functions return mutually exclusive 
lists when called with the same argument list. 7_lights points to an integer containing the original 
list size, and lights points to a pointer to the original list. After the function returns, the integer 
holds the new list length, and the pointer points to a new list. Both the integer and the pointer 
should be on the stack and should be initialized from the shader parameters using mi_eval to 
avoid overwriting the actual shader parameters, which should remain intact for the next shader 
call. 


The new list is a copy of the global light list (see 721_guery) with the matches with the original list 
removed. This function is slightly slower than the previous. The returned list remains valid until 


the next call to mi_inclusive_lightlist or mi_exclusive_lightlist. 


This function works with light groups introduced in mental ray 3.3. 


miScalar mi_lightprofile_value( 


void kv1p, /* opaque pointer to light profile */ 
miScalar phi, /* horizontal angle */ 

miScalar costheta, /* cos of vertical angle */ 

miVector *pos, /* sampling position on light */ 
miBoolean rel) /* return pure or relative value */ 


°-!' This function supports direct access to light profile data for photon emitter shaders. For a given 
light profile, identified by the opaque pointer v/p and obtained by mi_db_accessing the tag from 
the lightprofile parameter, this routine returns a light intensity. This intensity is either relative 
(normalized to a factor in the range 0..1) if rel is miTRUE, or the raw values from the vendor- 
supplied profile file (Candelas in the case of IES and Candelas per 1000 Lumen flux in the case of 
Eulumdat) if re/ is miFALSE. The phi and costheta arguments define the horizontal angle and the 
cosine of the vertical angle, respectively, as defined by the light profile. This function is intended 
for light emitter shaders that operate directly with angles; light shaders should use mi_lightprofile_ 
sample. 


miScalar mi_lightprofile_sample( 
miState *State, 
miTag light_profile, 
miBoolean rel) 
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>This is a variant of mi_lightprofile_value with a simplified interface suitable for light shaders. 
The v/p pointer is derived from accessing light_profile, and phi, costheta, and pos are derived from 
the direction and point variables of state. The rel flag is passed through. 


miBoolean mi_compute_irradiance ( 
miColor *result, 
miState *state) 


mi_compute irradiance computes the irradiance corresponding to indirect diffuse illumination at 
the intersection point given in state (state — point). This function is used in material shaders 
to add indirect illumination such as caustics or color bleeding. If state — pri is zero, miFALSE 
is returned. In mental ray 3.3 or later, the mit_compute_trradiance function, if called to evaluate 
irradiance from final gathering, will return the average of all alphas from finalgather rays. It 
was previously undefined. This allows a simple form of ambient occlusion mapping. In mental 
ray 3.4 or later, the final gather receive mode must be enabled in order to compute final gather 
contributions with this function. 


miBoolean mi_compute_irradiance_backside( 
miColor *result, 
miState x*state) 


>This function is equivalent to mi_compute_irradiance, except that it computes the irradiance on 
the back side of the surface, as defined by the surface normal. 


miBoolean mi_compute_avg_radiance( 


miColor *result, 
miState *state, 
miUchar face, j/*® *£* front. *b* back *+/ 


struct milrrad_options *irrad_options); /* options to overwrite */ 


typedef struct miIrrad_options { 
int size; /* size of the structure */ 


/* finalgather part */ 

int finalgather_rays; /* no. rays in final gather */ 
miScalar finalgather_maxradius; /* maxdist for finalgather */ 
miScalar finalgather_minradius; /* mindist for finalgather */ 


miCBoolean finalgather_view; /* radii in raster pixels? */ 
miUchar finalgather_filter; /* finalgather ray filter */ 
miUchar padding1 [2]; /* padding */ 


/* globillum part */ 
int globillum_accuracy; /* no. GI photons in estimation */ 
miScalar globillum_radius; /* maxdist for GI photons */ 
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/* caustics part */ 
int caustic_accuracy ; /* no. caustic photons in est. */ 
miScalar caustic_radius; /* maxdist for caustic photons */ 


/* this structure may be extended in the future */ 
} milIrrad_options; 


>This function basically subsumes mi_compute_trradiance and mi_compute_irradiance_backside 
functions under a common interface and additionally allows overriding quality parameters for 
final gathering and photons on a per-call basis. 


mi_compute_avg_radiance(result, state, ’f’, NULL) returns the same result as mi_compute_ 
irradiance(result, state) divided by z. In other words, mi_computeirradiance’s result 
is exactly a times brighter than mi_compute_avg_radiance. There is a similar relationship 
between mi_compute_avg_radiance(result, state, ’b’, NULL) (note the ’b’) and mi_ 
compute_trradiance_backside(result, state). 


For overriding finalgather and/or photon quality settings, a non- NULL pointer to a properly 
setup milrrad_options struct must be passed as fourth argument. All fields must be initialized 
before this struct is passed to mi_compute_avg_radiance. The macro miIIRRAD_DEFAULT may 
be used to initialize the structure with defaults from state — options, and a subset of the structure 
fields can be modified explicitly after that. 


Note that milrrad_options may be extended in future versions, but the explicit szze fields allows 
two-way compatibility. 


miBoolean mi_compute_volume_irradiance( 
miColor *result, 
miState *state) 


mi_compute_volume_irradiance computes the irradiance corresponding to indirect diffuse 
illumination at the point given in state (state — point). This function is used in volume shaders 
to add indirect illumination such as multiply scattered light or volume caustics. 


miBoolean mi_compute_directional_irradiance( 
miColor *result, 
miState *State, 
miScalar fr, 
miScalar gl, 
miScalar g2) 


This function is supported in mental ray 2.1.43 and later. mi_compute_directional_irradiance is a 
generalization of mi_compute_volume_trradiance that calculates the volume irradiance obtained 
when the forward or backward scattering directions (measured with respect to the light ray 
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direction) are preferred over sideways scattering. The parameters g/ and g2 are used to quantify 
two independent instances of these. Values between 0 and 1 specify forward scattering, while 
values between —1 and 0 specify backward scattering. A value of 0 indicates no preference, that 
is, diffuse scattering. The blending parameter r specifies to what extent the two choices should be 
(linearly) superimposed. For r = 0 only the choice with preferences specified by g2 contributes, 
while for r = 1 only the choice with preterences specified by g/ contributes. Commonly a positive 
choice for g/ is combined with a negative g2 and vice versa. Purely diffuse volume scattering may 
be computed more efficiently with mi_compute_volume_trradiance. An example polar diagram 
of irradiance dependent on the angle between scattering direction and light direction for values 
gl = —g2 = + is given in the figure below for r = 1.0,0.0, and 5. 


typedef enum miFinalgather_store_mode { 
miFG_STORE_COMPUTE ry 
miFG_STORE_SET = 2 
} miFinalgather_store_mode; 


miBoolean mi_finalgather_store( 
miColor *color, 
misState *State, 
int mode) 


>-2Creates a new finalgather point with the irradiance value color. Normally final gather points are 
created automatically based on accuracy settings, either during preprocessing, or during rendering 
when an irradiance is computed for a point with no nearby preexisting finalgather points. This 
function stores a point energy color explicitly, regardless of accuracy settings. The color value 
is either computed by mi_finalgather-store if mode is miFG_STORE_COMPUTE, using a procedure 
similar to mi_compute_irradiance, or the value specified by the caller is used directly if mode is 
miFG_STORE_SET. 
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If the mode is miFG_STORE_SET, state — point, state — normal and state — dist must be initialized 
before calling mi_finalgather_store. For best quality, state — dist should contain the distance to 
the closest object, but if this is not known or too expensive to probe, it may be left unchanged in 
the state. 


This function is useful for setting finalgather points in places where they would not normally be 
seen by preprocessing, such as the back sides of objects. This is especially useful for lightmap 
shaders because light maps that compute irradiances would otherwise look better on parts of the 
object seen by the camera. For example, the light map shader might use mz_finalgather-_store in 
compute mode to place finalgather points on vertices, for later lookup in output mode. 


3.26.3 Sampling with mi_sample 


miBoolean mi_sample( 
double *sample, 
int *instance, 
miState *state, 
miUshort dimension, 
miUint *n) 


This is mental ray’s primary generic sampling function. It can be used to sample arbitrary functions 
for evaluating integrals by deterministic sample points, which converge faster than their random 
counterparts and thus reduce rendering time. The mi_sample function is a high-level easy-to- 
use interface hiding all mathematical details of advanced quasi-Monte Carlo integration from the 
shader writer. sample is an array with dimension members that the new sample point will be stored 
into. Sample results are uniformly distributed in the range [0, 1)”. instance is the current sample 
number; it must point to an integer that is initialized to 0 before the first loop iteration. If there is 
no loop, a null pointer may be passed. state is the current shader state. dimension is the dimension 
of the sample, such as 3 for XYZ vectors. 7 must point to an integer that specifies the number of 
samples to take. If only a single sample is taken, 7 may be a null pointer. The body of the mi_ 
sample loop may not write to *sample or *n or vary dimension between any subsequent calls in 
the same loop because mi_sample computes the next sample incrementally from the previous. 


mi_sample has three main applications: 


1. generating single samples, which can be used in photon and other shaders for deciding 
on the kind of physical interaction like glossy, specular, or diffuse scattering, and then 
selecting a new quasi-random direction. This is the classical case of implementing random 
walk simulations with the von-Neumann-Ulam scheme. 


2. controlling an adaptive sampling loop, where the number of samples is not known in 
advance and the sampling loop will be terminated adaptively by the caller. This is the only 
mode where the caller may and must decide when to break from the loop. 


3. controlling a finite sampling loop. This is the classical case of quasi- Monte Carlo integration, 
where 7 samples are drawn and averaged. This can be used for sampling area light sources 
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or depth of field shaders. The advantage of knowing the number of samples 7 in advance is 
an increased convergence speed. 


Note that the returned sample point sample must be used as one point. This means that several 
one dimensional samples must not be assembled to yield a multidimensional sample, and that 
a multidimensional sample must not be used in order to simulate consecutive events. If, for 
example, 3D sampling vectors are computed with mi_sample, a single loop with dimension 3 
must be used, rather than a higher dimension to obtain other sampling values at the same time, 
or fewer to compute the X, Y, and Z direction separately. Samples from mi_sample must be 
used consecutively. The sequence should not be terminated prematurely, nor should samples be 
dropped, since rejection sampling will result in biased approximations. 


A call to mi_samp1e in single sample mode looks like: 


void a_single_sample(..., miState *state, ...) 


{ 


double sample[2]; 


mi_sample(sample, 0, state, 2, 0); 
/* use sample[0O] and sample[1] */ 


} 


The sampling dimension in this example is 2. Since only a single sample is required, no sample 
counting is indicated by passing a null pointer as *instance counter and to the required number 
of samples n. After the call to mi_sample, the array x holds a two-dimensional sample point of 
[0, 1)?. The function call always returns miFALSE in single sample mode. 


In the adaptive sampling mode, the number of samples to be taken is not known in advance, and 
the code must decide when to break from the loop (which it may not in the other two modes, 
where mi_sample returns miFALSE). mi_sample is then used the following way: 


void adaptive_sampling(..., miState *state, ...) 
{ 

double sample[5] ; 

int sample_number = 0; 


while (mi_sample(sample, &sample_number, state, 5, 0)) { 
/* use sample[0O], ..., sample[4] */ 
if (enough samples taken) 
break; 


} 


Adaptive sampling is indicated to mi_sample by passing a null pointer as the number of samples 7. 
The while loop is then controlled by the mi_sample call, which always returns miTRUE in adaptive 
sampling mode. The current sample number starting with 1 for the first sample is kept in sample- 
number. This variable must be initialized to zero in order to force initialization in mi_sample. 
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Note that in deterministic sampling, adaptive sampling (here, the break condition) cannot be 
controlled by the calculation of variance as in Monte Carlo context. This will result in biased 
approximations. Adaptive sampling here could be based on contrast calculations, for example. 
sample holds a sample point in the five-dimensional unit cube [0, 1)”. 


In the classical case, where the number of samples is known in advance, the deterministic sampling 
controlled by mi_sample very much resembles a Monte Carlo quadrature: 


void finite_sampling(..., miState *state, ...) 
{ 

const miUint samples = 16; 

double sample[2]; 

int sample_number = 0; 


while (mi_sample(sample, &sample_number, state, 2, &samples)) { 
/* use sample[0], sample[i] */ 


Here, all arguments of mi_sample are used. Unlike the previous adaptive sampling case, the 
number of samples is passed explicitly to mi_sample. Again the integer variable sample number 
is initialized to zero and passed by reference to instance. *state is the current state of the shader. 
mi_sample returns miTRUE for samples iterations of the loop, until finally miFALSE is returned to 
terminate the loop. The loop should not be terminated with a break or return statement, because 
then the internal state of state does not guarantee convergence of rendering any longer (that is, 
state —+ qmc-_instance and state — qmc_component are wrong until the shader terminates). In 
the loop, *instance provides the current sample number, starting at 1, until samples is reached. 
The loop controls a two-dimensional integration, where sample is an array of doubles with two 
elements. The vector sample is the sample point in the two-dimensional unit cube [0,1)*. The 
finite sampling mode exposes a faster convergence than the adaptive sampling mode. Exceptional 
convergence can be achieved if the number of samples is 


dimension—1 


samples = I] pe, 


j=) 


where p; are the prime numbers, 1.e., p1 = 2, p2 = 3, etc., and k; is a (positive) natural number. 
In two dimensions, 1.e., dimension = 2, samples should be a power of 2. In the special case of 
dimension = 1, any number of samples can be used in order to achieve optimal convergence. 


Note that if mz_sample controls the loop, it may take fewer samples than expected. For example, 
consider a sun, modeled as a disk area light source, with sampling set to request 8 samples. 
Assuming the sun is setting and only half of it is visible over the horizon, sampling the lower 
half cannot contribute any light. In this case, a light sampling function such as mi_sample_light 
(which is a specialization of mi_sample) may return miTRUE four times, and then abort the loop 
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by returning miFALSE for the fifth call. The shader should work for such early aborts, even if the 
very first call returns miFALSE. The shader should also not assume any valid result parameters, 
such as dot_nl, for a call to mi_sample that has returned miFALSE. 


3.26.4 RC Photon Functions 


The functions in this section implement photon tracing. They are to be used in photon shaders. 
If caustics or global illumination are enabled, rendering distinguishes two phases: photon tracing 
and scanline rendering/ray tracing. Photon tracing is done first. It sends photons from certain 
light sources into the scene. When a photon hits an object, the object’s photon shader is called, 
which then gets the opportunity to absorb the photon or use one of the mi_photon_* functions 
to let the photon continue. The photon functions can be used only in photon shaders. Photon 
shaders may not use regular ray tracing functions such as mi_trace_reflection. 


There are three main categories of photon tracing: specular, glossy, and diffuse. These terms define 
the distribution of the secondary photons in terms of the amount of scattering. Polished surfaces 
like chrome or clear glass are specular; unpolished surfaces such as aluminum or lightly frosted 
glass are glossy, and surfaces with no directional reflection or refraction such as paper are diffuse. 


Photon tracing and ray tracing are similar in many respects and use similar function calls. Although 
the operation underneath is quite different (tracing photons vs. tracing rays), a table of the 
operations in each phase shows the similarity as far as the shaders are concerned: 
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photons 

emanate from light sources 
call photon material shaders 
call photon volume shaders 
call photon emission shaders 


mi_photon_light 
mi_reflection_dir_specular 
mi_reflection_dir_glossy 
m1i_reflection_dir_anisglossy 
mi_reflection_dir_diffuse 
mi_transmission_dir_specular 
mi_transmission_dir_glossy 
mi_transmission_dir_anisglossy 
mi_transmission_dir_diffuse 
mi_scattering _dir_diffuse 
mi_scattering_dir_directional 
mi_scattering pathlength 
mi_photon_reflection_specular 
mi_photon-_reflection_glossy 
mi_photon_reflection_diffuse 
mi_photon_transmission_specular 
mi_photon_transmission_glossy 
mi_photon_transmission_diffuse 
mi_photon_transparent 
mi_photon_volume_scattering 
mi_store photon 


mi_store_volume photon 
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emanate from the camera 
call material shaders 

call volume shaders 

call light shaders 

call lens shaders 

call environment shaders 
mi_trace_eye 
m1i_reflection_dir 


mi_trace_reflection 


mi_trace_refraction 


mi_trace_transparent 


mi_compute_trradiance, 
. . di b ke 'd 3.x 
mi_compute_trradiance_backside 


mi_compute_avg_radiance>? 


mi_compute_volume_irradiance, 
mi_compute_directional irradiance 


There are three mi_photon_reflection* functions and three mi_photon_refraction_* functions (as 
well as a function for transparency and one for volume scattering). Why not just one reflection 
function and one transmission function, similar to mi_trace_reflection and mi_trace_refraction? 


The reason is that mental ray needs to know what type of reflections and transmissions the 
photon has undergone (its “path history”) to determine which photon map to store it in, when 
not to store the photon, and when to terminate the photon path. 


The photon reflection and transmission functions all follow the same pattern: first they check 
whether the intersected object is a caustic generator, if tracing caustic photons. If the object is 
not a caustic generator, the photon is not traced further and miFALSE is returned. A similar check 
is made for global illumination generating objects if tracing global illumination photons. Then 
a new state is set up with the appropriate ray type, reflection and refraction level, origin and 
direction (and the volume in the transmission case). 
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Photon shaders, photon volume shaders, and photon emission shaders are optional; if one is 
missing, mental ray uses built-in defaults. The default photon shader absorbs all photons, the 
default photon volume shader behaves like empty space, and the default photon emission shader 
behaves like a point light source emitting photons uniformly in all directions (that have a chance 
of contributing illumination — but this is only an optimization). 


Photon shaders can use the function mi_choose-_scatter_type to select which type of reflection 
or transmission the photon should undergo next. mi_choose-_scatter_type chooses a scatter type 
(reflection or transmission, diffuse, glossy, or specular) or absorption. The choice is made with 
probabilities depending on the scattering coefficients and the transparency. The scattering type 
with the highest scattering coefficients has the highest probability. 


In the following, d denotes diffuse, g denotes glossy, and s denotes specular, and the indices 7, g, 
and b mean red, green, and blue, respectively. Each of the nine scattering coefficients (specular 
R, G, B, glossy R, G, B, diffuse R, G, B) and the transparency must be in the range [0...1]. 
Furthermore, the RGB scattering coefficients must each add up to a total RGB value of (1, 1, 1). 


If these conditions are not met, the coefficients are adjusted so that they are met, and a warning 
is given (once). To find the probability for scattering (that is, choosing one of the six types of 
reflection or transmission), mental ray adds the red, green, and blue coefficients for diffuse, glossy, 
and specular. The largest component of the resulting compound RGB value is the probability for 
scattering. (Remember that the RGB sums cannot exceed 1.0.) 


Pisimas(dyt B+ §p dp + ee+ Giddy Hee HS). 


If a photon is not scattered, it is absorbed, so the absorption probability is 1.0 minus the the 
scattering probability. 


ow 


If the photon is not absorbed, the probability for diffuse transmission is the sum of the diffuse 
RGB components, divided by the sum of all nine components (diffuse, glossy, and specular R, 
G, and B), and multiplied by the transparency. 


i dp + de + ay 
d, + dg + dy +2, + 89 + Bp + Sr +5g + 5p 


The probability for diffuse reflection is the same, except that the component quotient is multiplied 
by 1.0 minus transparency instead of transparency. 


dy + dy +d, 
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Similar for glossy and specular reflection and transmission. If a certain scattering type is chosen, 
the three scattering coefficients (r, g, b) for that type of scattering are adjusted following the 
“Russian roulette” method. Note that glossy and diffuse scattering will not be chosen if caustics 
are being simulated — only specular scattering (or absorption) is possible then. 


The connection between the photon tracing and ray tracing phases is the mi_compute irradiance 
function. It allows material shaders (during image rendering) to get the caustics or global 
illumination color using the photons that were stored in the photon tracing phase. The function 
mi_compute_volume_irradiance is similar, but computes irradiance in a volume using the photons 
stored in the volume. 


This distinction is still valid if ray tracing is disabled and mental ray is reduced to scanline 
rendering in the second phase. For the purposes of photon tracing, scanline rendering can be 
considered a “ray tracing emulation” mode that achieves similar effects but never actually traces 
a ray, at the cost of not being able to control the ray direction. For example, if the trace off 
statement or -trace off command-line option is specified, it is still possible to generate caustics, 
but the second phase will be unable to compute raytraced reflections and refractions. 


miBoolean mi_photon_light ( 
miColor *energy, 
miState *state) 


traces a photon from a light source into the scene. The photon origin is state — org and the 
direction is state — dir. This function should be used only in photon emitting shaders. 


miBoolean mi_photon_reflection_specular ( 


miColor *energy, 
mistate *State, 
miVector *direction) 


traces a specularly reflected photon with energy in direction direction. This function may be used 
only in photon shaders. 


miBoolean mi_photon_reflection_glossy ( 


miColor *energy, 
mistate *State, 
miVector *direction) 


traces a glossily reflected photon with energy in direction direction. This function may be used 
only in photon shaders. 


miBoolean mi_photon_reflection_diffuse( 
miColor *energy, 
miState *State, 
miVector *direction) 
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traces a diffusely reflected photon with energy in direction direction. This function may be used 
only in photon shaders. 


miBoolean mi_photon_transmission_specular ( 


miColor *energy, 
miState *Sstate, 
miVector *direction) 


traces a specularly transmitted photon with energy in direction direction. This function may be 
used only in photon shaders. 


miBoolean mi_photon_transmission_glossy( 


miColor *energy, 
miState *State, 
miVector *direction) 


traces a glossily transmitted photon with energy in direction direction. This function may be used 
only in photon shaders. 


miBoolean mi_photon_transmission_diffuse ( 


miColor *energy, 
miState *Sstate, 
miVector *direction) 


traces a diffusely transmitted photon with energy in direction direction. This function may be 
used only in photon shaders. 


miBoolean mi_photon_transparent ( 
miColor *energy, 
miState *kstate) 


traces a specularly transmitted photon with energy in the direction indicated by the state (the 
same direction as the previous direction). This function may be used only in photon shaders. 


miBoolean mi_photon_volume_scattering ( 


miColor *energy, 
miState *State, 
miVector *dir) ; 


traces a photon, scattered by a volume, with energy in direction direction. This function may be 
used only in photon shaders. 
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void mi_store_photon( 
miColor *energy, 
miState *state) 


mi_store_photon stores a photon with the given energy in the photon map at the intersection point 
given in state state —> point. Only photons with non-zero energy are stored. Photons should only 
be stored at surfaces which have a diffuse component in order to limit the storage costs and reduce 
the rendering time. This function may be used only in photon shaders. 


void mi_store_volume_photon( 
miColor *energy, 
miState *state) 


This function is equivalent to the previous, except that it is used to store a photon in a volume 
instead of ona surface. It is used for volume caustics and volume scattering (such as volumic light 
beams and clouds). 


3.26.5 RC Direction Functions 


The functions in this section compute ray or photon directions. In both photon and ray tracing, 
shaders normally first compute a direction for secondary photons or rays using one of the 
functions with _dir in the name, and then call the corresponding photon or ray tracing function 
with the resulting direction. 


The functions mi_choose-scatter_type, mu-reflection_dir_.*, mi_transmission_dir-*, and mi- 
scattering_dir_* can also be used in other contexts than photon tracing, but they are listed in 
the photon tracing column above because they are most often used for that purpose. However, 
the glossy direction functions, for example, can just as well be used for ray tracing if the render- 
ing quality settings (contrast and sampling limits) are high enough to avoid noisy images. Using 
diffuse directions for ray tracing is unlikely to produce acceptable results due to noise. 


void mi_reflection_dir( 
miVector *dir, 
miState *state) ; 


Calculate the reflection direction based on the dir, normal, and normal_geom state variables. The 
returned direction dir can be passed to mi_trace_reflection. It is returned in internal space. 


void mi_reflection_dir_specular ( 
miVector *dir, 
miState *state) ; 


Same as mi-_reflection_dir: computes the mirror direction. Created for symmetry with the similar 
functions for glossy and diffuse reflection. 


3.26 Functions for Shaders 341 


void mi_reflection_dir_glossy ( 


miVector *dir, 
mistate *State, 
miScalar shiny) ; 


Choose a direction near the direction of ideal specular reflection (mirror direction). If shiny is 
low (for example, 5), a wide distribution of directions results; if shiny is high (for example, 100), 
a narrow distribution results. 


void mi_reflection_dir_anisglossy ( 


miVector *dir, 
miState *State, 
miVector *U, 
miVector *V, 
miScalar shiny_u, 
miScalar shiny_v); 


Like mi-_reflection_dir_glossy, but with different shinynesses in different directions. The u and v 
vectors specify the local surface orientation. 


void mi_reflection_dir_diffuse( 
miVector *dir, 
miState *Sstate) 


Choose a direction with a distribution according to Lambert’s cosine law for diffuse reflection. 


miBoolean mi_refraction_dir( 


miVector *dir, 
mistate *State, 
miScalar L0OYr in, 
miScalar ior_out) ; 


Calculate the refraction direction in internal space based on the interior and exterior indices of 
refraction zor_in and ior_out, and on dir, normal, and normal_geom state variables. The returned 
direction dir can be passed to mi_trace_refraction. Returns miFALSE and leaves *dir undefined in 
case of total internal reflection. 


miBoolean mi_transmission_dir_specular ( 


miVector *dir, 
mistate *State, 
miScalar Lor 15, 


miScalar ior out): 
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Same as mi_refraction_dir, since specular transmission occurs in the refraction direction. Created 
for symmetry with the similar functions for glossy and diffuse transmission. 


miBoolean mi_transmission_dir_glossy( 


miVector *dir, 

misState *State, 
miScalar 106 10. 
miScalar ior_out, 
miScalar shiny) ; 


Choose a direction near the direction of ideal specular transmission (the refraction direction). If 
shiny is low, a very wide distribution of directions results; if shiny is high, a narrow distribution 
results. 


miBoolean mi_transmission_dir_anisglossy ( 
miVector *xdir, 
miState *State, 
miScalar ior_in, 
miScalar ior_out, 
miVector *u, 
miVector ¥*v, 
miScalar shiny_u, 
miScalar shiny_v); 


Choose a direction for anisotropic glossy transmission. The w and v vectors specify the local 
surface orientation. 


void mi_transmission_dir_diffuse( 
miVector *dir, 
miState *State) 


Choose a direction with a distribution according to Lambert’s cosine law for diffuse transmission 
(also known as “diffuse translucency”). 


void mi_scattering_dir_diffuse( 
miVector *dir, 
miState *state) 


Choose a direction with a uniform probability over the whole sphere. The returned dir vector is 
normalized. This is useful for volume scattering. 
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void mi_scattering_dir_directional ( 


miVector *dir, 
miState *state 
miScalar directionality) 


Choose a direction with a probability determined by directionality. For values between —1 and 0 
it models volume backscattering (with —1 being the most directional), for a value of 0 it models 
diffuse (isotropic) volume scattering, and for values between 0 and 1 it models forward volume 
scattering. 


miScalar mi_scattering_pathlength( 
miState *state, 
miScalar k): 


Based on probability and exponential falloff, select a path length for a photon in a participating 
medium with density k. 


3.26.6 IMG Functions 


The IMG module of mental ray provides functions that deal with images. There are functions to 
read and write image files in various formats, and to access in-core frame buffers such as image 
textures. First, the functions that access frame buffers are listed. These functions are typically 
used by texture shaders, which can obtain an image pointer by calling mi_db_access with the 
image tag as an argument. All these functions do nothing or return defaults if the zmage pointer 
is 0, or if the x or y coordinate is out of bounds. They do not check whether the frame buffer 
has the correct data type. All these functions are available in all shaders, including displacement, 
geometry, and output shaders. 


void mi_img_put_color( 
milmg_image *image, 


miColor *color, 
int x; 
int y) 


Store the color color in the color frame buffer image at coordinate x y, after performing 
desaturation or color clipping, gamma correction, compensating for premultiplication, and 
dithering. Not all of these steps may be performed, and the behavior is dependent on the options 
colorclip, premultiply, desaturate, gamma, and dither as given on the command line or in the .mi 
file. This function works with 1, 2, or 4 components per pixel, and with 8, 16, or 32 (float) bits 
per component. The normal range for the R, G, B, and A color components is [0, 1] inclusive. 
For 32 bit (float) frame buffers only compensation for premultiplication is done. 
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void mi_img_get_color( 
milmg_image *image, 


miColor *color, 
int X, 
int y) 


This is the reverse function to miimg_put_color. It returns the color stored in a frame buffer at 
the specified coordinates. Gamma compensation and premultiplication, if enabled by miimg- 
mode, are applied in reverse. The returned color may differ from the original color given to mi- 
img_put-_color because of color clipping and color quantization. 


void mi_img_put_scalar ( 
milmg_image *image, 


float scalar, 
int x, 
int y) 


Store the scalar scalar in the scalar frame buffer zmage at coordinate x y, after clipping to the range 
[0,1]. Scalars are stored as 8-bit or 16-bit unsigned values. This function is intended for scalar 
texture files of type miIMG_S or miIMG_S_16. 


void mi_img_get_scalar ( 
milmg_image *image, 


float *Scalar, 
int ye 
int y) 


This is the reverse function to miimg_put-scalar. It returns the scalar stored in a frame buffer at 
the specified coordinates, converted to a scalar in the range [0, 1]. If the frame buffer pointer is 0, 
or if the x or y coordinate is out of bounds, the scalar is set to 0. 


void mi_img_put_vector ( 
milmg_image *image, 


miVector *vector, 
int a 
int y) 


Store the X and Y components of the vector vector in the vector frame buffer image at coordinate 
x y, after clipping to the range [—1, 1]. Vectors are stored as 16-bit signed values. This function 
is intended for vector texture files of type miIMG_VTA or miIMG_VTS. Warning: this function 
accesses 16-bit UV vectors, not the floating-point XYZ normal and motion vectors stored in 
frame buffers. This means it’s largely obsolete because hardly anyone still uses explicit bump 
basis vectors, and output shaders should almost certainly use mi_img_put_normal instead! 
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void mi_img_get_vector ( 
milmg_image *image, 


miVector *vector, 
int z=. 
int y) 


This is the reverse function to miimg_put_vector. It returns the UV vector stored ina frame buffer 
at the specified coordinates, with coordinates converted to the range |—1, 1]. The Z component 
of the vector is always set to 0. If the frame buffer pointer is 0, or if the x or y coordinate is out 
of bounds, all components are set to 0. Again, make sure you should not be using mi_img_get- 
normal. 


void mi_img_put_depth( 
milmg_image *image, 


float depth, 
int x; 
int y) 


Store the depth value depth in the frame buffer image at the coordinates x y. The depth value 
is not changed in any way. The standard interpretation of the depth is the (positive) distance of 
objects from the camera origin. mental ray uses this function internally to store —state — dist 
if the depth frame buffer is enabled with an appropriate output statement. By convention, the 
value 0.0 signifies infinite distance. 


void mi_img_get_depth( 
milmg_image *image, 


float *depth, 
int =: 
int y) 


Read the depth value to the float pointed to by depth from frame buffer image at the coordinates 
x y. If the image pointer is 0, or if the x or y coordinate is out of bounds, return the MAX_FLT 
constant from limits.h. 


void mi_img_put_normal ( 
milmg_image *image, 


miVector *normal , 
int x 
int y) 


Store the normal vector normal in the frame buffer zmage at the coordinates x y. The normal 
vector is not changed in any way. This function can also be used for the motion vector frame 


buffer. 
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void mi_img_get_normal ( 
milmg_image *image, 


miVector *normal, 
int =. 
int y) 


Read the normal vector normal from frame buffer image at the coordinates x y. If the image 
pointer is 0, or if the x or y coordinate is out of bounds, return a null vector. This function can 
also be used for the motion vector frame buffer. 


void mi_img_put_label( 
milmg_image *image, 


miUint label, 
arb z; 
int y) 


Store the label value /abel in the label frame buffer zmage at the coordinates x y. The label value 
is not changed in any way. 


void mi_img_get_label ( 
milmg_image *image, 


miUint *label, 
int =. 
int y) 


Read the label value to the unsigned integer pointed to by label from frame buffer image at the 
coordinates x y. If the image pointer is 0, or if the x or y coordinate is out of bounds, return 0. 


miBoolean mi_img_tonemap ( 
milmg_image *outimage, 
milmg_image *inimage, 
miImg_tonemap *para) 


performs a tone mapping on the provided input image and stores the result in the given output 
image. Tone mapping is commonly performed from an output shader. The input and output 
image pointer may refer to the same image. The behaviour of the tone mapper is determined by 
the provided parameters. The structure is given as 


struct milmg_tonemap { 
miScalar ref; 
miScalar tolerance; 
miScalar low_out; 


3.26 
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miScalar Bd out: 
miScalar low_in; 
miScalar Hd. 3is 
miColor lum_weight ; 
int n_bins; 

int x_res; 

int y.res; 

int x Lo; 

int FoiO3 

int x his 

int y_hi; 
miBoolean linear ; 
miBoolean desaturate; 
miTag map ; 


re 


The fields of the miImg_tonemap structure have the following meanings 


ref gives a reference intensity. The input color will be scaled by this value before any 
transformation is performed. Unless there is a specific reaason to the contrary the default 
value of 1 should be used. 


tolerance gives an error tolerance for the tone-mapping calculations. A good value is 0.01. 
low_out gives the lowest non-black intensity to be contained in the output image. 
hi_out gives the highest intensisty to be contained in the output image. 


low-in gives the highest intensity of the input image on which the color transformation is 
to be based. All greater intensities are mapped to white. 


hi_in gives the lowest intensity in the input image to be considered. All intensities below 
are mapped to black. 


lum_weight gives the weights used to compute luminance from a color. 


n_bins gives the number of bins into which color intensity values of an image are to be 
sorted. If the number of bins is 1, then a linear mapping of color intensities is performed, 
which is local and does not involve information from neighboring pixels. For non-local 
tone mapping values of around 100 are a good choice. 


X_res, y_res gives the size of a rectangle over which the color values are averaged before 
they are tone mapped. The default values of zero for both fields is a good choice for most 
cases. 


x_lo, y_lo, x_hi, y_hi give a sub-rectangle within the image. Tone mapping is only applied 
to this rectangle. 


linear. If this flag is set, then local linear tone mapping is performed. 
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e desaturate flags whether the resulting tone-mapped color values should be desaturated 


such that no color component is above the /7_out value. 


e map is a reference to a one-dimensional scalar array decribing how color intensities are 
mapped for tone mapping. This field allows overriding the internal mapping calculations 
of the tone map routines and is optional. The default value is a null tag. 


Math functions include common vector and matrix operations. More specific noise and rendering 
functions can be found in the next two sections, Noise Functions and Auxiliary Functions. 


“I 


“I 


void mi_vector_neg( 
miVector *r ) 


void mi_vector_add( 


miVector *r, 

miVector *a, 

miVector *b) 
a+b 


void mi_vector_sub( 


miVector *r, 

miVector *a, 

miVector *b) 
a—b 


void mi_vector_mul( 
miVector *r, 
miScalar f) 


™1 
Sy 
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void mi_vector_div( 


miVector *Ir, 
miScalar f ) 
rice} ; (If f is zero, leave unchanged.) 


void mi_vector_prod( 


miVector *r, 

miVector *a, 

miVector *b) 
¥:=axb 


miScalar mi_vector_dot( 
miVector *a, 
miVector *b) 


Ql 
SS] 


miScalar mi_vector_norm( 
miVector a) 


\|@ || 
void mi_vector_normalize( 
miVector *Tr ) 
f= ill (If 7 is a null vector, leave 7 unchanged.) 
void mi_vector_min( 
miVector *r, 
miVector *a, 
miVector *b) 
ria) a < by > a 3 by 
fp ib, 2 @ 2+ 8 
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void mi_vector_max( 
miVector *r, 
miVector *a, 
miVector *b) 
feb, 7? &y b.. 
Pies ? 
P= | woh, 7 a by 
miScalar mi_vector_det( 
miVector *a, 
miVector *b, 
miVector *C) 
a De, De 
ay by Cy 
m be G 
miScalar mi_vector_dist( 
miVector *a, 
miVector *b) 
\|a — D| 
void mi_matrix_null( 
miMatrix x) 
kK = 


Oo. Oo Oo © 
OOO O 
oO a oO © 
Oo Oo oo © 
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void mi_matrix_ident ( 


miMatrix *) 
1 oO 0G 2 
oe 10 9 
io GO 2 1 9g 
0 0 0 1 


miBoolean mi_matrix_isident ( 
miMatrix a) 


Return miTRUE if a is the identity matrix, and miFALSE otherwise. 


void mi_matrix_copy( 
miMatrix Yr; 
miMatrix a) 


miBoolean mi_matrix_invert ( 


miMatrix ag 
miMatrix a) 
| a; te (Returns miFALSE if the matrix cannot be inverted.) 


void mi_matrix_prod( 


miMatrix ae 
miMatrix a, 
miMatrix b) 


Kw=AS SG 
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void mi_matrix_rotate( 
miMatrix a, 
const miScalar xrot, 
const miScalar yrot, 
const miScalar zrot) 


Create a rotation matrix a rotating by xrot, then yrot, then zrot, in radians. 


void mi_matrix_rotate_axis( 
miMatrix a, 
miVector const ¥*v, 
miScalar const r) 


This function is similar to the previous, except that the rotation is specified with an axis and 
an angle. The resulting matrix will rotate a point r radians about the axis v according to the 
right-hand rule. v must have unit length, otherwise the result is undefined. 


void mi_matrix_solve( 


miScalar *X, 
miMatrix A, 
miScalar *B, 
int c) 


*-* Solve the system of linear equations A - X = B for X. A is a [4,4] matrix, but X and B are 
[4, c| (row major) matrices. For c = 1 they are simple vectors and the function solves A - X = B 


for X. In the case c = 4, A and B are rectangular [4, 4] matrices and the function computes the 


matrix division A\ B. Using this function is both faster and more precise than explicitly computing 
Aq! xB. 


All the following transformation functions may be called with identical pointers r and v. The 
vector is transformed in-place in this case. If the matrix m is a null pointer, no transformation is 
done and v is copied to r. If the result of a transformation is a point in homogeneous coordinates 
with a w component that is not equal to 1.0, the result vector’s x, y, and z components are divided 
by w. For point transformations, a w component of 1.0 is implicitly appended to the v vector at 
the vector-matrix multiplication. For vector transformations the w component is implicitly zero. 
Note the distinction between object and light transformations — both sets deal with object space, 
but the former uses the current object’s object space and the latter uses the current light’s object 
space. 
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float mi_matrix rot_det( 
miMatrix a) 


Return the determinant of the 3 x 3 rotation part of matrix a. 


void mi_point_transform( 


miVector *r, 

miVector *V, 

miMatrix m) 
F:=0-M 


void mi_vector_transform ( 


miVector *I , 
miVector *V, 
miMatrix m) 
r:=0-M Only the upper left 3-by-3 submatrix is used since this is a vector transform. The 


translation row in the matrix is ignored as w is implicitly assumed to be 0. 


void mi_vector_transform_T( 


miVector *T, 
miVector *V, 
miMatrix m) 
¥:= o-M! The transpose of the upper left 3-by-3 submatrix is used for the vector 


transformation. The w component of v is implicitly assumed to be 0. This function is required 
for transformation of normals. 


void mi_point_to_world( 
miState * const’ state, 
miVector * const Ir, 
miVector * const v) 


Convert internal point v in the state to world space, r. 
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void mi_point_to_camera( 
miState * const state, 
miVector * const Ir, 
miVector * const v) 


Convert internal point v in the state to camera space, r. 


void mi_point_to_object ( 
miState * const state, 
miVector * const Ir, 
miVector * const v) 


Convert internal point v to the object space of the current object (illuminated point), r. 


void mi_point_to_light ( 
miState * const state, 
miVector * const Ir, 
miVector * const v) 


Convert internal point v in the state to the object space of the current light. This function (and the 
other five light transformation functions described below) are similar to the corresponding object 
transformation functions except that they use state — light_instance instead of state — instance 
to locate the correct object space transformation matrices. 


void mi_point_to_raster ( 
mistate * const state, 
miVector * const r, 
miVector * const v) 


Convert internal point v in the state to 2D raster space, r. Raster space dimension is defined by 
the camera resolution. 


void mi_point_from_world( 
miState * const state, 
miVector * const fr, 
miVector * const v) 


Convert point v in world space to internal space, r. 
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void mi_point_from_camera( 
misState * const state, 
miVector * const Ir, 
miVector * const v) 


Convert point in camera space v to internal space, r. 


void mi_point_from_object ( 
mistate * const state, 
miVector * const Ir, 
miVector * const v) 


Convert point v in the object space of the current object (illuminated point) to internal space, r. 


void mi_point_from_light ( 
mistate * const state, 
miVector * const Ir, 
miVector * const v) 


Convert point v in the object space of the current light as found in state — light_instance to 
internal space, r. 


void mi_vector_to_world( 
mistate * const state, 
miVector * const Ir, 
miVector * const v) 


Convert internal vector v in the state to world space, r. Vector transformations work like point 
transformations, except that the translation row of the transformation matrix is ignored. The 
resulting vector is not renormalized. Vector transformations transform normals correctly only 
if there is no scaling. For correct transformation of normals use the normal transformations 


described below. 


void mi_vector_to_camera( 
miState * const state, 
miVector * const fr, 
miVector * const v) 


Convert internal vector v in the state to camera space, 7. 
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void mi_vector_to_object ( 
miState * const’ state, 
miVector * const Ir, 
miVector * const v) 


Convert internal vector v to the object space of the current object (illuminated point), r. 


void mi_vector_to_light ( 
mistate * const state, 
miVector * const Ir, 
miVector * const v) 


Convert internal vector v in the state to object space of the current light as found in state — light- 
instance, Y. 


void mi_vector_from_world( 
miState * const state, 
miVector * const Ir, 
miVector * const v) 


Convert vector v in world space to internal space, r. 


void mi_vector_from_camera( 
miState * const’ state, 
miVector * const fr, 
miVector * const v) 


Convert vector in camera space v to internal space, r. 


void mi_vector_from_object ( 
miState * const’ state, 
miVector * const Ir, 
miVector * const v) 


Convert vector v in the object space of the current object (illuminated point) to internal space, r. 
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void mi_vector_from_light ( 
mistate * const state, 
miVector * const Ir, 
miVector * const v) 


Convert vector v in object space of the current light as found in state — light_instance to internal 
Space, *. 


void mi_normal_to_world( 
miState * const state, 
miVector * const Ir, 
miVector * const v) 


Convert internal normal v in the state to world space, r. Normal transformations work like 
vector transformations, except that the transpose of the inverse transformation matrix used. The 
resulting vector is not renormalized. This ensures that if a vector and a normal are orthogonal in 
one coordinate system they remain orthogonal after they have been transformed to a different 
coordinate system. This holds for arbitrary, not necessarily orthogonal transformations. The 
vector transformations described above transform normals correctly only if there is no scaling. 


void mi_normal_to_camera( 
miState * const state, 
miVector * const fr, 
miVector * const v) 


Convert internal normal v in the state to camera space, 7. 


void mi_normal_to_object ( 
mistate * const’ state, 
miVector * const Ir, 
miVector * const v) 


Convert internal normal v to the object space of the current object (illuminated point), 7. 
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void mi_normal_to_light ( 
miState * const state, 
miVector * const fr, 
miVector * const v) 


Convert internal normal v in the state to object space of the current light as found in state — light_ 
instance, Y. 


void mi_normal_from_world( 
misState * const state, 
miVector * const Ir, 
miVector * const v) 


Convert normal v in world space to internal space, r. 


void mi_normal_from_camera( 
misState * const’ state, 
miVector * const Ir, 
miVector * const v) 


Convert normal in camera space v to internal space, r. 


void mi_normal_from_object ( 
misState * const state, 
miVector * const Ir, 
miVector * const v) 


Convert normal v in the object space of the current object (illuminated point) to internal space, 
r 


void mi_normal_from_light ( 
miState * const state, 
miVector * const Ir, 
miVector * const v) 


Convert normal v in object space of the current light as found in state — light_instance to internal 
space, 7. 
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3.26.8 Noise Functions 


The functions in this group provide pseudo-random numbers, quasi-Monte Carlo numbers (using 
low-discrepancy sequences that converge faster than pseudo-random numbers), and deterministic 
Perlin noise. 


miScalar mi_random(void) 


Return a random number in the range [0,1). This is similar to drand48 in the standard Unix 
libraries, but it is available on all platforms including Windows NT, which does not support 
drand48. 


miScalar mi_srandom ( 
long seed) 


Begin a new random number sequence for mi_random. This is equivalent to the standard Unix 
library function srand48. 


miScalar mi_erandom( 
unsigned short seed[3]) 


Return a random number in the range [0, 1), based on the given seed. This allows shaders to create 
private random number generators by initializing a private seed array to some arbitrary but 
constant values, and passing it to mi_erandom without the chance of other functions or threads 
disturbing the sequence by “stealing” random numbers (assuming they do not have access to the 
private seed). This is equivalent to the standard Unix library function erand48. 


miScalar mi_par_random( 
miState *state) 


Return a parallel-safe random number in the range [0, 1). Parallel-safe random numbers can be 
used in parallel rendering to produce consistent results that do not change when the number 
of machines or threads changes, or when the execution order changes. All shaders that use this 
function share the same internal seed value. This function should not be used in geometry shaders, 
displacement shaders, photon shaders, output shaders, or _imit functions of shaders because the 
initial seed of the random number sequence is undefined in these cases. 


miScalar mi_spline( 
misScalar tC; 
const int O. 
miScalar * const ctl) 
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This function calculates a one-dimensional cardinal spline at location t. The t parameter must 
be in the range 0...1. The spline is defined by 7 control points specified in the array ctl. There 
must be at least two control points. To calculate multi-dimensional splines, this function must be 
called once for each dimension. For example, spline can be used three times to interpolate colors 
smoothly. 


miScalar mi_noise_id( 
const miScalar _ p) 


Return a one-dimensional coherent noise function of p. All six noise functions compute a modified 
Perlin noise function from the given one, two, or three dimension parameters such that the noise 
changes gradually with changing parameters. The modification of the classical algorithm avoids 
large-scale periodical behavior at lattice points, such that the noise is smooth on all levels. (This 
makes the algorithm perform slower than classical Perlin noise.) The returned values are in the 
range 0...1, with a bell-shaped distribution centered at 0.5 and falling off to both sides. This 
means that 0.5 is returned most often, and values of less than 0.0 and more than 1.0 are never 
returned. See [Perlin 85]. 


miScalar mi_noise_2d( 
const miScalar i. 
const miScalar v) 


Return a two-dimensional noise function of u, v. 


miScalar mi_noise_3d( 
miVector * const p) 


Return a three-dimensional noise function of the vector p. This is probably the most useful 
noise function; a simple procedural texture shader can be written that converts a copy of the 
state—point vector to object space, passes it to m1_noise_3d, and assigns the returned value to the 
red, green, and blue components of the result color. The average feature size of the texture will 
be approximately one unit in space. 


miScalar mi_noise_id_grad( 
const miScalar_ p, 
miScalar * const g) 


Return a one-dimensional noise function of p. The gradient of the computed texture at the 
location p is assigned to *g. Gradients are not normalized. 


miScalar mi_noise_2d_grad( 
const miScalar a 


3.26 Functions for Shaders 361 


const miscalar wT; 
miScalar * const gu, 
miScalar * const gv) 


Return a two-dimensional noise function of u, v. The gradient is assigned to *gu and *gv. 


miScalar mi_noise_3d_grad( 
miVector * const p, 
miVector * const g) 


Return a three-dimensional noise function of the vector p. The gradient is assigned to the vector 


g. 


miScalar mi_unoise_1d() 
miScalar mi_unoise_2d() 
miScalar mi_unoise_3d() 
miScalar mi_unoise_id_grad() 
miScalar mi_unoise_2d_grad() 
miScalar mi_unoise_3d_grad() 


These functions are similar to the regular noise functions, except that the returned distribution is 
uniform. All returned values are roughly equally likely. 


3.26.9 KD-Tree Functions>** 


KD trees are acceleration structures that store 3D points in a k-dimensional space. They provide 
fast lookup of elements that are close to a given location. Stored elements consist of two parts: the 
location vector and associated arbitrary data. All data stored ina KD tree must have the same size, 
but different trees may have different sizes. Sizes over about 100-200 bytes are not recommended 
though, to keep memory usage low and lookups fast; if more data is needed pointers to the data 
should be stored instead of the data itself. 


KD trees are implemented as mental ray database elements. However, access and edit functions 
are slightly different. The main difference is that, when a KD tree is accessed or edited, a pointer 
to a “handle” is returned, not just the pointer in to DB element memory. This pointer (always 
called tree below) is only valid in the thread that has opened it — it is not possible to access a 
KD tree and keeping the pointer for multiple rendered rectangles because different rectangles 
are rendered simultaneously in different threads. For example, it is legal to access a KD tree in 
a shader state function in state imit mode and unpinning it in state exit mode, but it is not legal 
to do the same in shader init or exit functions because shaders may stay initialized and in use in 
multiple threads until rendering finishes. mi_shaderstate-_set is a good way to pass open KD tree 
pointers to other shaders. 


Like all other data structures under shader control, KD trees cannot be used across a network 
of machines. Every host can create and access its own KD trees, but it cannot access or edit 
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trees on other hosts. Although KD trees are scene elements that are identified by tags, which 
might indicate that they are network-transparent, they are not — there is no mechanism that 
synchronizes multiple writes. Any attempt to do so may overwrite some changes with others, or 
fail to propagate changes across the network at the right time. 


miTag mi_kdtree_create( 
mikdtree_type type, 
miUint datasize) 


>> The type argument must have the value miKDTREE_3D, which specifies that the tree works with 
3D points in space. Future versions may allow different lookup dimensions or methods. The 
datasize argument is the size of the data not including the size of location coordinates, fixed for 
all elements of the new KD tree. The returned tag identifies the new KD tree for future accesses 
and edits. 


struct mikKdtree *mi_kdtree_edit( 


miTag tag, 
const void *sShared_data, 
miUint shared_data_size) 


>> This opens a tree for adding new elements. The shared_data argument may point to a data 
structure that is stored while the KD tree is open for editing. mental ray will not use this data 
in any way, but pass it to the insert callback later when the tree is rebalanced (see below). The 
shared_data-size is the size of the structure that shared_data points to. The caller should release 
shared_data after mi_kdtree_edit returns, if it was allocated, because mental ray makes a copy 
of the data and keeps it until the next rebalancing operation (see below). Multiple simultaneous 
edits are allowed, mental ray resolves any conflicts automatically. However, the same tree may 
not be open for reading (mi_kdtree_access) an writing (mi_kdtree_edit) simultaneously, even if the 
conflicting access and edit happen in different threads. 


miBoolean mi_kdtree_add( 
struct mikKdtree *tree, 
const void *data, 
const miScalar  point[]) 


>> Add a new element to the KD tree. The tree pointer must have been obtained from a previous 
call to mi_kdtree_edit. The size of the stored data must agree with the data-_size specified when 
the tree was created. The poznt is the 3D position where the data will be stored. This function is 
fast, the element is added to the buffer of elements scheduled for adding. The function returns 
miFALSE on failure, for example if tree comes from mi_kdtree_access instead of mi_kdtree_edit. 


Since mi_kdtree_add is much faster than mi_kdtree_edit, it is a good idea to add as many points 
as possible inside an edit/unpin bracket. Do not edit, add, unpin for every point. 
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miBoolean mi_kdtree_unpin( 
struct miKdtree *tree) 


°° This function ends accessing or editing. Every call to mi_kdtree_access and mi_kdtree_edit 
should have a corresponding mi_kdtree_unpin. The tree pointer, which must have been obtained 
from an access or edit, becomes invalid. However, if the KD tree is not unpinned until the end of 
the job (ie. a photon bundle or a rendered rectangle), this is done automatically. This automatic 
unpinning should be used with care; while keeping the tree accessed or edited for a long time is 
efficient because the add function is faster than the access and edit functions, it does not protect 
the called from simultaneous access and edit, which is illegal. The function returns miTRUE; there 
are currently no failure modes. 


typedef miBoolean ((miKdtree_insert_callback) 


(void *callback_data, 
void *data, 

miScalar pointl[], 

const void *xshared_data)); 


struct mikKdtree *mi_kdtree_access( 


miTag tag, 
mikdtree_insert_callback *callback, 
void *callback_data) 


>> Opens a KD tree for read-only lookups or iteration over all elements. Simultaneous access calls 
for different KD trees, identified by different tags, are legal. The returned tree pointer identifies 
the accessed KD tree until the the access is terminated with a call to mi_kdtree_unpin. 


After a tree was edited and points were added, it requires a processing phase called rebalancing. 
Rebalancing is an expensive operation, and mental ray tries to defer it as long as possible, in case 
another point gets added later. However, accessing the tree for lookup requires a rebalanced tree, 
so the rebalancing phase occurs when mi_kdtree_access is called. 


Rebalancing integrates each point previously stored with mi_kdtree_add, and not yet integrated 
by a previous rebalance, into the KD tree. If a nonzero callback argument is specified, this callback 
will be called for each point to integrate. The callback may modify the point and data fields of the 
point, which were both specified with mi_kdtree_add. The callback also receives the shared_data 
structure specify in the last mi_kdtree_edit call. Finally, the callback receives the opaque callback- 
data pointer from mi_kdtree_access; this can be used to pass a C++ this pointer to provide context. 
If the callback returns miFALSE, the point is rejected and not added. 


For example, the callback may be used for energy renormalization. Light sources may cast photons 
into the scene, and store each photon into a single KD tree where it hits a surface. However, the 
light sources do not know how many photons will eventually be cast, so they cast each one with 
the light energy. When all photons have been cast, it is necessary to divide the energy of each 
photon in the KD tree by the number of photons for the originating light source. This would be 
done by the callback; the photon energy would be stored in the point data by mi_kdtree_add, 
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and information about the light emitter (which is important to find the number of photons to 
divide by) would be stored in the shared_data by mi_kdtree_edit. It would be inefficient to store 
the light emitter identifier with each added photon. 


typedef miBoolean ((mikKdtree_lookup_callback) 


(void *callback_data, 
const void *data, 
const miScalar point[])); 


miUint mi_kdtree_lookup( 


struct mikKdtree *tree, 

const miScalar point[], 

miUint max_n, 

miScalar max_dist, 
miScalar *max_dist_used, 
miKkdtree_lookup_callback *callback, 

void *callback_data) 


°° This function returns points near point in the KD tree tree, which must have been opened 
with mi_kdtree_access. It finds the max_n closest elements, which are closer than max_dist. The 
distance to the most distant element found is stored in *max_dist_used, if this pointer is nonzero. 
The number of elements found is returned. The callback is called on each element found, with 
the opaque callback_data pointer. If the callback returns miFALSE, mi_kdtree_lookup returns 
immediately. For example, if the KD tree is used for storing photons, a simple callback could just 
sum the energy of all photons. 


miBoolean mi_kdtree_iterate( 


struct mikKdtree *tree, 
miKdtree_lookup_callback *callback, 
void *callback_data) 


°° This function is similar to a lookup, but it returns all points in the KD tree, instead of just 
those that are close to a given point. Again, the iteration stops if the callback returns miFALSE. mi_ 
kdtree_iterate returns miFALSE on failure, for example if tree comes from mi_kdtree_edit instead 
of mi_kdtree_access. 


miBoolean mi_kdtree_delete( 
miTag tag) 


°° Deletes the KD tree from the database. All KD tree handles must be closed by calling mi- 
kdtree_unpin before calling this function. The function returns miTRUE; there are currently no 
failure modes. 
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3.26.10 Shading Models 


The following functions are provided for support of shaders, to simplify common mathematical 
operations required in shaders: 


miScalar mi_fresnel ( 


miScalar 10r in, 

miScalar ior_out, 
miScalar factorl, 
miScalar factor2); 


Compute the reflected intensity according to Fresnel, given the index of refraction zor_in in the 
current medium and the index of refraction zor_out in the medium on the other side, which the 
ray is about to enter. The factors define the medium opacities. 


(ee) + ee) 


lin f2 + out fi lin fi + tour + fr 


miScalar mi_fresnel_reflection( 


mistate *Sstate, 
miScalar 10r in, 
miScalar Lor_out): 


Call mi_fresnel with parameters appropriate for the given indices of refraction zor_in and ior_out, 
and for the dot_nd state variable. 


miScalar mi_phong_specular ( 


miScalar spec_exp, 
misState *State, 
miVector *dir) ; 


Calculate the Phong factor based on the direction of illumination dir, the specular exponent spec- 
exp, and the state variables normal and dir. The direction must be given in internal space. 


void mi_fresnel_specular ( 


miScalar *NS, 
misScalar *Ks, 
miScalar spec_exp, 
miState *State, 
miVector *dir, 
miScalar 10r_in., 


miScalar iot_out); 
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Calculate the specular factor ms based on the illumination direction dir, the specular exponent 
spec_exp, the inside and outside indices of refraction zor_im and ior_out, and the state variables 
normal and dir. ks is the value returned by mi_fresnel, which is called by mi_fresnel_specular. The 
direction must be given in internal space. 


miBoolean mi_cooktorr_specular ( 


miColor *result, 
miVector *dir_in, 
miVector *dir_out, 
miVector *normal, 
miScalar roughness, 
miColor *ior); 


Calculate the specular color result according to the Cook-Torrance reflection model for incident 
direction dir_in, reflection direction dir_out at a surface with normal normal. The roughness is the 
average slope of surface microfacets. ior is the relative index of refraction for three wavelengths 
(ior_out/ior_in for red, green, and blue). All indices must be 1.0 or greater; if not they are clamped 
to 1.0. See [Foley 90]. 


miScalar mi_blinn_specular ( 


miVector *dir_in, 
miVector *dir_out, 
miVector *normal, 
miScalar roughness, 
miScalar Lor) 2 


Like mi-_cooktorr_specular, but only for one wavelength. Only one index of refraction zor is 
needed, and the result is a scalar. If zor is less than 1.0, it is clamped to 1.0. See [Foley 90]. 


miScalar mi_blong_specular ( 


miVector *dir_in, 
miVector *dir_out, 
miVector *normal, 
miScalar roughness, 
miStalar ior): 


This is similar to mi_blinn_specular, but implements a hybrid of Blinn and Phong shading instead 
of true Blinn shading. It is included separately to support the Softimage Blinn shading model. 


miScalar mi_ward_glossy( 


miVector *dir_in, 
miVector *dir_out, 
miVector *normal, 


miScalar shiny) ; 
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Calculate the value of the isotropic Ward glossy reflection model for incident direction dir_in, 
reflection direction dir_out at a surface with normal normal and shinyness shiny. dirin should 
point towards the point, while dzr_out and normal should point away from the point. Shiny 
should be low (for example 5) for wide glossy reflection, and high (for example 100) for narrow 
glossy (nearly specular) reflection. 


miScalar mi_ward_anisglossy ( 


miVector *dir_in, 
miVector *dir_out, 
miVector *normal , 
miVector *U, 

miVector *V, 

miScalar shiny_u, 
miScalar shiny_v) ; 


Calculate the value of the anisotropic Ward glossy reflection model for incident direction dir_in, 
reflection direction dir_out, surface normal normal, and the anisotropic orientation determined 
by two perpendicular vectors u and v. The shinyness in the u and v direction is shiny_u and shiny-_ 
v, respectively. dir_in should point towards the point, while dir_out and normal should point 
away from the point. uw and v should be perpendicular, and also perpendicular to the normal. 


miScalar mi_schlick_scatter ( 


miVector *dir_in, 
miVector *dir_out, 
miScalar directionality) ; 


Calculate the value of the Schlick volume scattering model for incident direction dir_in, scattering 
direction dir_out, and directionality directionality. dirin should point towards the point, while 
dir_out should point away from the point. directionality must be between —1 and 1. For values 
between —1 and 0 it models backscattering (with -1 being the most directional), for a value of 0 it 
models diffuse (isotropic) scattering, and for values between 0 and 1 it models forward scattering. 


miRay_type mi_choose_scatter_type ( 


miState *State, 
float transp, 
miColor *diffuse, 
miColor *glossy, 
miColor *specular) 


In photon shaders it is generally important (although not required) to generate only one photon 
per photon interaction. To make this happen this function can be used to select one of several 
new photon types. The function returns: miPHOTON-REFLECT_SPECULAR, miPHOTON_REFLECT-_ 
GLOSSY, miPHOTON_REFLECT_DIFFUSE, miPHOTON_TRANSMIT_SPECULAR, miPHOTON_TRANSMIT_ 
GLOSSY, miPHOTON_TRANSMIT_DIFFUSE or miPHOTON_ABSORBED. The return type is based on 
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incoming coefficients and chosen in such a way that the most important component is chosen 
most often. Notice that for caustics simulations the diffuse and glossy components are ignored. 
Also note that the sum of the diffuse, glossy and specular coefficients should be less than or 
equal to one within each of the red, green, and blue color bands, and that mi_choose_scatter_type 
modifies the input coefficients and scales them correctly based on the probability of generating 
a photon of that type. To obtain a correct result the shader must use the modified coefficients 
in the computations performed after mi_choose-_scatter_type has been used. The probability for 
reflection is 1 — transp. See page 337 for a more detailed explanation. 


miRay_type mi_choose_simple_scatter_type( 


miState *state, 

miColor *refl_ diffuse, 
miColor *refl_specular, 
miColor *trans_diffuse, 
miColor *trans_specular) 


This is a simplified version of m1_choose-_scatter_type that simply returns the diffuse and specular 
terms for reflected and transmitted light. Unlike mz_choose_scatter_type, it does not support glossy 
interactions. 


int mi_choose_lobe( 
misState *State, 
miScalar rr): 


In atwo-lobed volume scattering model, choose lobe 1 or 2 based on the probability r of the first 


lobe. 


3.26.11 Color Profile Functions>** 


These routines may be used within shaders to transform their arguments from one color space to 
another or to identify the color spaces currently in use. 


miUinti mi_colorprofile_renderspace_id() 
>*returns the identifier associated with the current rendering color space. 


miUinti mi_colorprofile_internalspace_id() 


°4returns the identifier associated with the internal color space. 
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miUinti mi_colorprofile_ciexyz_id() 
**returns the identifier associated with the CIE XYZ color space. 


miBoolean mi_colorprofile_internal_to_render ( 
miColor *color) 


>-4assumes that the given color is in internal color space and transforms it in-place to the rendering 


color Space representation. 


miBoolean mi_colorprofile_render_to_internal ( 
miColor *color) 


>-4assumes that the given color is in rendering color space and transforms it in-place to the internal 


color space representation. 


miBoolean mi_colorprofile_ciexyz_to_render ( 
miColor *color) 


°tassumes that the given color is in CIE XYZ color space and transforms it in-place to the 


rendering color space representation. 


miBoolean mi_colorprofile_render_to_ciexyz( 
miColor *color) 


°-4assumes that the given color is in rendering color space and transforms it in-place to the CIE 


XYZ color space representation. 


miBoolean mi_colorprofile_internal_to_ciexyz( 
miColor *color) 


>-*assumes that the given color is in internal color space and transforms it in-place to the CIE 


XYZ color space representation. 


miBoolean mi_colorprofile_ciexyz_to_internal ( 
miColor *color) 


>-4assumes that the given color is in CIE XYZ color space and transforms it in-place to the internal 


color space representation. 
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3.26.12 Auxiliary Functions 


miBoolean mi_lookup_color_texture ( 


miColor *color, 
miState *State, 
miTag tag, 

miVector *coord) 


tag is assumed to be a texture as taken from a color texture parameter of a shader. This function 
checks whether the tag refers to a shader (procedural texture) or an image, depending on which 
type of color texture statement was used in the .mi file. If tag is a shader, coord is stored 
in state—tex, the referenced texture shader is called, and its return value is returned. If tag is 
an image, coord is brought into the range (0..1,0..1) by removing the integer part, the image is 
looked up at the resulting 2D coordinate, and miTRUE is returned. If the texture is marked with 
the filter keyword, multi-level pyramid filtering is performed, a procedure related to classical 
mip-map textures. In both cases, the color resulting from the lookup is stored in *color. 


typedef struct { 


miScalar eccmax; 
miScalar max_minor; 
miScalar circle_radius; 
miBoolean bilinear; 
miScalar spare[10]; 


} miTexfilter; 


miBoolean mi_lookup_filter_color_texture ( 


miColor *color, 
miState *State, 
miTag tag, 
miTexfilter *paras, 
miMatrix Sr 


This function provides higher quality filtering than the multi-level pyramid filtering of mi_ 
lookup-color_texture described above using a transformation ST which transforms the coordinate 
system centered in the current raster position in screen space to texture space. The functions 
mi_texture_filter_project and mi_texture_filter_transform are provided for helping to calculate this 
transformation matrix. 


This function expects that tag does not refer to a texture shader, that is, it works only on texture 
images. It will return miFALSE when used with incorrect parameters or if a projection failed. 


In the filtering algorithm a circle around the current raster position is projected to an ellipse in 
texture space, and returns the average color of all texture pixels inside the ellipse. If the texture 
defined by tag is a pyramid texture, multi-level lookup of the texture pixels is performed to speed 
up the filtering. In the algorithm the level calculation is based on the minor radius of the ellipse. 
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The filtering can be controlled by choosing different values in paras. If paras is a null, default 
values for medium filter quality are used. 


The eccmax field in miTexfilter specifies the maximum allowed eccentricity of the ellipse. It 
must be equal to or greater than 1.0. The eccentricity is defined by the ratio of the major and 
minor radius. Under severe projective distortion the ellipse can have a very large eccentricity and 
too many texture pixels would be covered by the elliptical area, resulting in long rendering times. 
In order to limit the filtering time in these cases, the eccentricity threshold can be specified. If the 
eccentricity is greater than this value, the minor radius of the ellipse is made larger allowing for 
a potentially higher level in the texture image pyramid since the level calculation is based on the 
minor radius. 


In this calculation a level is selected where the minor radius of the ellipse has a maximum length 
of max_minor texture pixels. In each successive level in the image pyramid the radius is divided 
by two, and there are fewer pixels inside the elliptical area. The useful range for eccmax is 
approximately 10 to 30, higher values will result in better antialiasing. For max_minor the range 
should be 3 to 8. Higher values result in better antialiasing. 


The size of the projected screen-space circle can be modified with the circle_radius parameter. 
Larger values will result in more blurring since the elliptical area is also made larger. Smaller 
values will increase the aliasing. The useful range for this field is 0.4 to 1.0. 

When a magnification area is detected, that is, an area in which the pixels are not compressed (the 
elliptical area is smaller than a texture pixel), bilinear texture pixel interpolation can be switched 


on by setting the bzlinear field to miTRUE, which results in a more blurry image. 


See page 249 for an example. 


miBoolean mi_lookup_scalar_texture ( 


miScalar *Scalar, 
miState *State, 
miTag tag, 

miVector *coord) 


This function is equivalent to milookup_color_texture, except that tag is assumed to refer to a 
scalar texture shader or scalar image, as defined in the .mi file with a scalar texture statement, 
and a scalar is looked up returned in *scalar. Note that filtering of scalar textures (enabled with 
filter scalar texture statements) is supported only in mental ray 3.1.2 and later. 


miBoolean mi_lookup_vector_texture ( 


miVector *VeECtOr, 
miState *State, 
mitag tag, 


miVector *coord) 
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This function is also equivalent to mi_lookup_color_texture, except that tag is assumed to refer toa 
vector texture shader or vector image, as defined in the .mi file witha vector texture statement, 
and a vector is looked up returned in *vector. Vector textures cannot be filtered. 


miBoolean mi_texture_filter_project( 


miVector pis]. 
miVector EIS!) 
miState *const state, 
miScalar Giese 7. 
miUint space) 


This function helps in calculating the screen to texture space transformation matrix required by 
mi_tlookup_filter_color_texture. It projects three points including the current raster position onto 
the current intersection primitive (state—pri) plane and calculates the texture coordinates in the 
intersections. If state—pri is null, or if the projection fails, miFALSE is returned. 


This function assumes that the current intersected object has a texture space associated and uses 
space as an index into the texture space. The three screen space points are returned in p, the 
corresponding two dimensional texture space points are put into t. The first point in the array is 
always the central raster position (0,0), the others are inside a disc with radius of disc_r from this 
central position. Note that the points are relative to the central position, absolute screen space 
coordinates are not used. The value of disc_r should be set to 0.5 in most cases, since the full 
pixel is projected to texture space. However, when there are highly curved objects in the scene, 
a smaller value can effectively remove projection problems where the projected points are far 
outside the hit triangle primitive. 


miBoolean mi_texture_filter_transform( 


miMatrix Sls 
miVector pis), 
miVector tl3]) 


This function helps in calculating the screen to texture space transformation matrix required 
by milookup_filter_color_texture. The three two dimensional screen space points in p and the 
corresponding three two dimensional texture space points form a linear equation which is solved 
for the transformation matrix. See page 249 for an example. This function returns miFALSE if the 
linear equation mentioned above has no solution. 


miScalar mi_luminance( 
miState *State, 
miColor *color) ; 


Return the luminance of color, by multiplying each RGB component by a factor (default $) and 
adding the results. The factors can be changed with the luminance weight statement, or the 
luminance_weight field in the miOptions structure. The purpose of having a single function to 
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do this calculation is to make luminance calculations in shaders consistent across all shaders, and 
making the weight easily changeable in one central place. This is for shaders only; mental ray 
does not calculate luminances or use the weights in any way. 


miBoolean mi_tri_vectors( 


mistate *State, 
int which, 
int ntex, 
miVector **Ka, 
miVector **«D , 
miVector **C) 


All the information in the state pertains to the interpolated intersection point in a triangle. This 
function can be used to obtain information about the uninterpolated triangle vertices. Together 
with the barycentric coordinates in the state, parameters retrieved with mi_tri_vectors may be 
interpolated differently by the shader. The which argument is a character that controls which 
triple of vectors is to be retrieved: 


the points in space 

the normal vectors 

the motion vectors 

the texture coordinates of texture space ntex 
the U bump basis vectors 

the V bump basis vectors 


the first surface derivative in U (dPdu) 
the first surface derivative in U (dPdv) 
the second surface derivative d?Pdu? 


the second surface derivative d?Pdv” 


the second surface derivative d7Pdudv 
the user vectors 


A pointer to the vectors is stored in *a, *b, and *c. The shader may not modify these vectors. 
They are stored in the space used when the scene was created (either object space or camera space 
depending on state — options — render_space); the original data is accessed without implicit 
transformation to internal space. If the requested triple is not available, miFALSE is returned. This 
function relies on state — pri; it only works if the shader has not modified this variable, as some 
ray-marching volume shaders do. 


This function may not be called in displacement shaders because triangles do not yet exist at that 
stage. Displacement displaces vertices, not triangles; triangles are built from final vertices later. It 
also may not be called for hair objects, because hair is not based on triangles. (mental ray 3.2 and 
later detect this case and return miFALSE for hair objects.) 


374 3 Using and Writing Shaders 


miBoolean mi_texture_interpolate( 


misState *State, 
miUint space, 
miScalar *result) 


°*This function interpolates the current intersection state — pri texture coordinates, using 
the barycentric coordinates from the state. The texture space index is given with space. The 
coordinates are written to the array result which must be allocated large enough according to the 
dimension of the texture space. This function is needed only for geometry with texture coordinates 
that have more or fewer than three dimensions. Standard 3D texture coordinates should be read 
from state — tex_list. Non-3D texture coordinates are supported only for subdivision surfaces 
and raw primitive lists. Use the miQ_TEXTURE_DIM mode of mi_query to find the dimension of a 
texture coordinate. 


miBoolean mi_raster_unit( 


miState *State, 
miVector *X, 
miVector *y ) 


>2Transforms a pair of X and Y unit vectors in raster space to the current object space. In other 
words, the returned x and y vectors specify the size of a pixel in object space. This information 
is useful for selecting filter parameters in the shader, such as bump map precisions or texture 
lookups. This function assumes a pinhole camera. The orientation of the surface at the current 
shading point is not taken into account. 


miBoolean mi_query ( 
const miQ_type query, 
miState *const state, 


miTag tag, 
void * const result, 
«J 


Return various pieces of information about the current state of mental ray. query is the request 
code specifying what piece of information to query; state is the shader state, tag is the tag of the 
DB element to query, if any, and result is a pointer to the variable to store the results in. Some 
queries do not require a tag; in this case miNULLTAG must be passed as tag. Some queries require 
extra arguments in addition to the four standard arguments. mi_query returns miFALSE if the 
queried value is not available or an unknown type code is used. The following guery codes are 
available (st is short for state): 


query code 


miQ_VERSION o o- char 
O O 


. mental ray version string 


mental ray compilation date 


miQ_DATE char 
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query code 


miQ_NUM_GLOBAL_LIGHTS int number of global lights 

miQ_GLOBAL_LIGHTS miTag * array with global light tags 

miQ_NUM_TEXTURES int” number of textures in state->tex_ 
list 

miQ_NUM_BUMPS?? int * number of bumps in state x, y 
bump lists 

miQ_GEO_LABEL O miUint translator-defined triangle label 

miQ_GEO_DATA O miTag user data block of current object 

miQ_GEO_HAS_DERIVS?°” a miBoolean | validity of state derivatives 


miQ_GEO_HAS_DERIVS2° miBoolean | validity of state second deriva- 
‘ tives 

miQ_PRI_BBOX_MIN miVector object-space bounding box of 
intersected primitive 

miQ_PRI_BBOX_MAX miVector object-space bounding box of 
intersected primitive 

miQ_TEXTURE_DIM miUint dimension of nth texture space 
of intersected primitive (7 is fifth 
argument) 

miQ_SCENE_ROOT_GROUP>*? miTag the root group of the scene from 
the render statement; useful for 
custom scene traversals 

miQ_SCENE_BBOX_ALL miVector[2] | world-space bounding box of all 
geometry 

miQ_SCENE_BBOX_SHADOW miVector[2]| bounding box of all shadow- 
casting geometry 

miQ_SCENE_BBOX_GLOBILLUM_G miVector[2]| bounding box of all globillum- 
casting geometry 

miQ_SCENE_BBOX_GLOBILLUM_R miVector[2]| bounding box of all globillum- 
receiving geometry 

miQ_SCENE_BBOX_CAUSTIC_G miVector[2]| bounding box of all caustic- 
casting geometry 

miQ_SCENE_BBOX_CAUSTIC_R miVector[2]| bounding box of all caustic- 
receiving geometry 

miQ _TILE_PIXELS int[4] lower left and upper right tile 
pixel coord 

miQ_TILE_SAMPLES int[4] same but including filter source 
margin 

miQ_PIXEL_SAMPLE>? miScalar[2] | set up QMC sequences for sam- 
pling, and return a jitter value for 
lightmap shaders. See page 3.23 
for an example. 


376 


query code 
miQ_TILE_SAMPLES 


miQ_INST_FUNCTION 


miQ_INST_GLOBAL_TO_LOCAL 
miQ_INST_LOCAL_TO_GLOBAL 
miQ_INST_IDENTITY 


miQ_INST_ITEM 
miQ_INST_PARENT 
miQ_INST_HIDE 
miQ_INST_VISIBLE 
miQ_INST_TRACE 
miQ_INST_SHADOW 
miQ_INST_CAUSTIC 


miQ_INST_GLOBILLUM 


miQ_INST_DECL 
miQ_INST_PARAM_SIZE 
miQ_INST_PARAM 
miQ_INST_MATERIAL 
miQ_INST_LABEL 
miQ_INST_DATA 
miQ_INST_AREA 


miQ_TRANS_INTERNAL_TO_WORLD 


miQ_TRANS_INTERNAL_TO_CAMERA 


miQ_TRANS_INTERNAL_TO_OBJECT 


miQ_TRANS_WORLD_TO_INTERNAL 


miQ_TRANS_CAMERA_TO_INTERNAL 


miQ_TRANS_OBJECT_TO_INTERNAL 


int[4] 


milag 


miMatrix * 
miMatrix * 
miBoolean 


milag 
milag 
miBoolean 
miUint 
miUint 
miUint 
miUint 


miUint 


milag 
int 

void * 
milag 
miUint 
milag 
miScalar 


miMatrix * 


miMatrix * 


miMatrix * 


miMatrix * 


miMatrix * 


miMatrix * 
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st tag resul 


same but including filter source 
margin 


optional procedural transforma- 
tion 

instance transformation 

inverse instance transformation 
miTRUE if identity transtorma- 
tion 

instanced scene element 

leaf instance parent (0 otherwise) 
instance is inactive 

visible to primary rays 

visible to secondary rays 
invisible to shadow rays 
bitmap: 1=enable casting, 2=en- 
able receiving, 3=disable casting, 
4=disable receiving 

bitmap: 1=enable casting, 2=en- 
able receiving, 3=disable casting, 
4=disable receiving 

inherited parameter declaration 
inherited parameter size 
inherited parameters 

inherited material 
translator-defined instance label 
user data block 

light instances only: area of area 


light 


internal to world space transtor- 
mation 

internal to camera space trans- 
formation 

internal to object space transfor- 
mation 

world to internal space transtfor- 
mation 

camera to internal space trans- 
formation 

object to internal space transfor- 
mation 
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query code 
miQ_TRANS_WORLD_TO_CAMERA 


miQ_TRANS_WORLD_TO_OBJECT 
miQ_TRANS_CAMERA_TO_WORLD 
miQ_TRANS_OBJECT_TO_WORLD 
miQ_GROUP_MERGE_GROUP 
miQ-GROUP_NKIDS 
miQ_GROUP_KID 
miQ_GROUP_LABEL 
miQ_GROUP_DATA 
miQ_OBJ_TYPE 
miQ_OBJ_VISIBLE 
miQ_OBJ_TRACE 
miQ_OBJ_SHADOW 
miQ_OBJ_VIEW_DEPENDENT 
miQ_OBJ_CAUSTIC 
miQ_OBJ_GLOBILLUM 


miQ_OBJ_LABEL 
miQ_OBJ_DATA 


miQ_LIGHT_TYPE 
miQ_LIGHT_AREA 


miQ_LIGHT_EXPONENT 
miQ_LIGHT_CAUSTIC_PHOTONS 


miQ_LIGHT_CAUSTIC_PHOTONS_ 
EMIT?! 
miQ_LIGHT_GLOBAL_PHOTONS 
miQ_LIGHT_GLOBAL_PHOTONS_EMIT?:! 


miQ_LIGHT_ENERGY 
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st tag resi 


miMatrix * 
miMatrix * 
miMatrix * 


miMatrix * 


miBoolean 
int 

milag 
miUint 
milag 

int 
miBoolean 
miBoolean 
miBoolean 
miBoolean 
miUint 
miUint 
miUint 
milag 

int 

int 


miScalar 
int 


int 
miColor 
miColor 


milag 


world to camera space transtfor- 
mation 
internal to world space transfor- 
mation 
camera to world space transfor- 
mation 
object to world space transfor- 
mation 


miTRUE if connected 

number of child instances 

nth child (n is fitth argument) 
translator-defined group label 
user data block 


O=polygonal, 1=surfaces 

visible to primary rays 

visible to secondary rays 
invisible to shadow rays 
contains view-dependent  sur- 
faces 

O=none, 1=casts, 2=receives, 
3=both 

O=none, 1=casts, 2=receives, 
3=both 

translator-defined object label 
user data block 


O=point, 1=directional, 2=spot 
O=none, 1=rectangle, 2=disc, 
3=sphere 

distance falloff, 7 in 1/r” 
number of caustic photons to 
store 

number of caustic photons to 
emit 

number of globillum photons to 
store 

number of globillum photons to 
emit 

energy for caustics and globil- 
lum 
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miQ LIGHT_SHADER milag tag of light shader 
miQ_LIGHT_EMITTER miVector tag of light photon emitter 
shader 

light position 

light direction 

U size of rectangular area light 
V size of rectangular area light 
normal vector of disc area light 
radius of disc area light 

radius of spherical area light 
miScalar radius of cylinder area light 
miVector axis of cylinder area light 

int number of samples in U direc- 
tion 

number of samples in V direc- 
tion 

outer cone angle of spot light 
light has a shadow map 

light label 

user data block 


miVector 
miVector 
miVector 
miVector 
miVector 
miScalar 

miScalar 


miQ_-LIGHT_ORIGIN 
miQ_-LIGHT_DIRECTION 
miQ_LIGHT_AREA_R_EDGE_U 
miQ_LIGHT_AREA_R_EDGE_V 
miQ_LIGHT_AREA_D_NORMAL 
miQ_LIGHT_AREA_D_RADIUS 
miQ_LIGHT_AREA_S_RADIUS 
miQ_LIGHT_AREA_C_RADIUS 
miQ_LIGHT_AREA_C_AXIS 
miQ_LIGHT_AREA_SAMPLES_U 


Oo O 0 0 0 0 0 OO 8 @ 
@®eeeeeeee ®@ 


miQ_LIGHT_AREA_SAMPLES_V int 


miQ_LIGHT_SPREAD miScalar 
miQ_LIGHT_USE_SHADOWMAP miBoolean 
miQ_LIGHT_LABEL int 
miQ_LIGHT_DATA milag 


material is opaque to shadow 
rays 


miQ_MTL_OPAQUE miBoolean 


miQ_MTL_SHADER 
miQ_MTL_DISPLACE 
miQ_MTL_SHADOW 
miQMTL_VOLUME 
miQ_-MTL_ENVIRONMENT 
miQ_MTL_CONTOUR 
miQ_MTL_PHOTON 
miQ_MTL_PHOTONVOL 


miQ_FUNC_USERPTR 
miQ_FUNC_LOCK 
miQ_FUNC_TYPE 


miQ_FUNC_DECL 
miQ_FUNC_NEXT 
miQ_FUNC_INDIRECT 
miQ_-FUNC_PARAM_SIZE 


miQ_FUNC_RESULT_SIZE 
miQ_FUNC_PARAM 


oS oo oOo Oo DO) © Oo Oo 


milag 
milag 
milag 
milag 
milag 
milag 
milag 
milag 


void ** 
miLock * 


int 


milag 
milag 
milag 


int 


int 
void * 


material shader 
displacement shader 
shadow shader 
volume shader 
environment shader 
contour shader 
photon shader 

photon volume shader 


user pointer in shader instance 
local shader instance lock 
0=C/C++, 1=phen., 2=output 
file 

tag of shader declaration 

next shader in shader list 

take params from this shader 
size of shader parameters in 
bytes 

shader result size in bytes 
shader parameters 
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st tag resul 


see above | same for state — shader 
e o milag tag of the currently running 
shader 

one of miSHADER_*, as specified 
by the calling mz_call_shader 

set thread-local shader data 
pointer (see page 409) 

retrieve thread-local shader data 
pointer 

get list of all valid thread-local 
shader data pointers, and the list 
S1Ze 


miQ_FUNC_* 
miQ_FUNC_TAG>? 


miQ_FUNC_CALLTYPE>? ! int 


miQ_FUNC_TLS_SET>:! void * 


miQ_FUNC_TLS_GET>:! void * 


miQ_FUNC_TLS_GETALL>:! void *, int 


miQ DECL_LOCK o e milLock* | shared by all shader instances 
miQDECL_TYPE o e@ int mil YPE_* result type 
miQ_DECL_RESULT_SIZE Oo e int result size, 4 unless struct 
miQ_DECL_NAME o e  char* shader name 

miQ_DECL_PARAM o e  char* ascii-encoded parameter decla- 


ration 

shader declaration version 

same for state — shader 

width of image in pixels 

height of image in pixels 

num of bits per component 
(8,16,32) 

num of components (1,2,3,4) 
image allows filtering 

color frame buffer desaturation 
mode 

color frame buffer dithering 
mode 

color frame buffer premultipli- 
cation mode 

color frame buffer color clipping 
mode 

color frame buffer gamma factor 


int 
see above 
int 
int 
int 


miQ_DECL_VERSION 
miQ_DECL_* 
miQ_IMAGE_WIDTH 
miQ_IMAGE_HEIGHT 
miQ_IMAGE_BITS 


Oo O 0 @ O 
@® @ @® 0 ® 


int 
miBoolean 
miBoolean 


miQ_IMAGE_COMP 
miQ_IMAGE_FILTER 
miQ_IMAGE_DESATURATE 


O 
® 


miQ_IMAGE_DITHER miBoolean 


miQ_IMAGE_NOPREMULT miBoolean 


miQ_IMAGE_COLORCLIP miBoolean 


miQ_IMAGE_GAMMA double 


user data contents 

user data declaration if any, or 0 
next user data block in chain, or 
QO 

translator-defined user data label 


o e  char* 
o e@ milag 
o e milag 


miQ_DATA_PARAM 
miQ_DATA_DECL 
miQ_DATA_NEXT 


miQ_DATA_LABEL miUint 
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query code 
miQ_DATA_PARAM_SIZE 
miQ_DATA_NEEDSWAP 


st tag resul 


o e int size of user data block in bytes 
miBoolean | requires byte-swapping by 


shader 


horizontal angle where the light 
profile starts 

horizontal angle where the light 
profile ends 

smallest value of the cosine of the 
profile vertical angle. 

largest possible value of the co- 
sine of the profile vertical angle 
largest intensity value of the 
profile 

number of interpolation points 
in the horizontal direction 
number of interpolation points 
in the vertical direction 


miQ_LIGHTPROFILE_PHI_MIN>! muScalar 


miQ_LIGHTPROFILE_PHI_MAX>! muScalar 


miQ_LIGHTPROFILE_COSTHETA_ miScalar 
MIN?! 
miQ_LIGHTPROFILE_COSTHETA_ 
MAX?! 
miQ_LIGHTPROFILE_INTENSITY_ 
MAX?! 


miQ_LIGHTPROFILE_PHI_RES?>'! 


miScalar 


miScalar 


int 


miQ_LIGHTPROFILE_THETA RES?! int 


miQ_FINALGATHER_STATE>? O=not a finalgather ray 
(grand)child, 1=finalgather ray 
(grand)child in a tile rendering, 
2=finalgather ray (grand)child 


in finalgather precomputing 


‘<9 b> 


The “o” symbol in the state column indicates that the state is not used. The “o” symbol in the tag 
column means that miNULLTAG must be passed. Some queries can specify a state instead of a tag. 
Their query codes are indicated with a *, which stands for any of the preceding codes whose names 
begin with the same prefix; in this case mi_query will take the current shader (state — shader) 
instead of an arbitrary tag. This is slightly faster than passing a tag. 


The result type in the table indicates the type of the variable that _query accepts a pointer to: 
to obtain an integer result from mi_query (the table lists an “int”), a pointer to an integer must be 
passed as the fourth argument (“int *”). For mi_query, “function” is synonymous with “shader”. 


The result of themiQ_INST_VISIBLE, miQ_INST_SHADOW, miQ_INST_TRACE, and miQ_INST_CAUSTIC 
queries depend on whether a scene DAG or leaf instance tag is passed. A scene DAG instance 
contains the flags specified by the scene description language when the instance was created. A 
leaf instance contains the effective instance flags for rendering, that is, with instance inheritance 
and object flags taken into account. The miQ_INST_VISIBLE etc. modes should be used instead of 
the miQ_OBJ_VISIBLE etc. modes because they return the same modes that mental ray uses when 
rendering. 


The result vectors of the miQ_LIGHT_ORIGIN and miQ_LIGHT_DIRECTION queries are defined in 
internal space if the light instance tag is passed, otherwise the vectors are defined in local space. 


The miQ_TILE_* codes are supported by mental ray 2.1.34.107 or later. They describe the 
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location and size of the currently rendered image tile. The returned values are in the order 
xlow xhigh ylow yhigh. The sampled area may be larger than the tile due to filtering and 
jittering. 


The query codes miQ_NUM_TEXTURES and miQ_GEO_LABEL may only be used if state — pri has not 
been modified by the shader or calling shader. Ray-marching volume shaders sometimes clear 
this state variable. Both are not supported in displacement shaders. miQ_GEO_LABEL also returns 
miFALSE if the object is not marked tagged and no polygon/surface labels exist. In mental ray 3.3, 
the miQ_GEO_LABEL mode may be used from displacement shaders; this did not work in earlier 
versions. 


Note that a return type of miMatrix * means that the address of a pointer must be passed, not 


the address of a matrix. This reduces the number of bytes that mi_query has to copy from 64 
(sixteen floats) to only four (or eight, on some CPU architectures). 


miBoolean mi_shaderstate_set( 


miState *State, 
const char *key, 
void *value, 
inet valsize, 
int lifetime) 


>2Store a data block *value under the name key (which has become const in mental ray 3.3). The 
data block can be retrieved by key with mi_shaderstate_get later. Shorter keys are slightly faster 
to hash and compare. valsize is the size of the value block to store. A copy of *value is made. If a 
data item with the same key exists, it is replaced with the new one. If value or valsize are null, an 
existing data item with the same key is deleted and none is created. The lifetime controls when 
the data item is deleted: at the end of the current eye ray if lifetime is miSS_LIFETIME_EYERAY, or 
at some later point, but no later than the end of the rectangle, if it is miSS_LIFETIME_RECT. The 
latter is slightly faster. In any case, data items are separate for each host, thread, and rectangle. 


Data items stored with this mechanisms are intended for communication between shaders called 
during evaluation of a single eye ray, both upstream and downstream. For example, a material 
shader may set a data item to be picked up by any later light shader, or by the root lens shader. It 1s 
a replacement for state — user, which works only downstream and causes conflicts if more than 
one data item is needed. The mechanism is only available in eye ray context during rendering, but 
not in geometry, output, displacement, or other shaders that do not get called as a consequence 
of an eye ray. As a special case, use in lightmap shaders is supported. 


Note that transparency in rasterizer mode (formerly called Rapid Motion) is not performed by 
casting rays that could carry shader state, but by compositing at a later stage. For this reason it is 
not possible to transport shader state through a call to mi_trace_transparency In rasterizer mode. 


void *mi_shaderstate_get ( 
struct miState x*state, 
const char *key, 
int *valsize) 
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27 ook up a data element previously stored with mi_shaderstate_set, under the same key, and 
return a pointer to the stored value. Also return the size of the stored value in *valsize, unless 
valsize is a null pointer. If no data element is found, a null pointer is returned and valsize is 


undefined. 


void mi_shaderstate_enumerate( 


miState *State, 
miBoolean (*cb) (void *arg, char *key, void *val, int vsz, int l), 
void *karg) 


>2The callback cb is called for each known item, with the opaque arg pointer, key, value, value 
size, and lifetime. If cb is a null pointer, the list is printed using mz_info. This function is intended 
for debugging only; the implied linear search is inefficient. Callback mode is useful to interpret 
the contents of the value pointer; mz_info merely prints an address. 


miBoolean mi_fb_put ( 


miState *State, 
int 7B; 
void *data) 


Store data into the sample so that it gets filtered and stored in user frame buffer fb later. The type 
of the data to copy from *data is determined by the frame buffer type as defined in the options 
block. The frame buffer number fb must be a number equal to or greater than 0, corresponding to 
the fb” number in the frame buffer statements. (mental ray 3.3 and earlier only supported the 
range 0..7.) If this frame buffer was not defined, this function has no effect and returns miFALSE. 
The data is stored in the current sample (i.e., the current location for which the primary ray was 
cast), and is filtered to create frame buffer pixels after all samples in the region have been taken. 
There is no way to store user frame buffer data in arbitrary locations with this function. It should 
be called for all samples and all defined user frame buffers to avoid leaving holes; if user frame 
buffer data is left undefined in a sample because mi_fb_put was not called, the data defaults to 
zero and is filtered as such. 


Output shaders may not use this function because there is no notion of “samples” during 
output shading; instead, they must use the standard miimg_put_* functions with an offset 
of miRC_IMAGE_USER + fb. Shaders may get the data type of a frame buffer by inspecting 
state — options — image_types|n]. Similarly, final gathering, light mapping, displacement, and 
geometry shaders may not use mi_fb_put and mi_fb_get because the frame buffers are only available 
during frame rendering. **The data type of a frame buffer is stored in state — options — images- 


info. 


miBoolean mi_fb_get( 
miState *State, 
int fb, 
void *data) 
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Retrieve data from user frame buffer fb. The type of the data copied to *data is determined by 
the frame buffer type as defined in the options block. It will never be larger than 16 bytes (the 
size of a miColor). The frame buffer number fb must be in the range 0...7. If this frame buffer 
was not defined, this function returns miFALSE, and no data is stored. This function is intended 
to let shaders retrieve data that may have been stored by shaders called in later ray generations, 
but like 1_fb_put it is limited to the current sample. Again, output shaders may not use this 
function because there is no notion of “samples” during output shading; instead, they must use 
the standard miimg_get_* functions with an offset of miRC_IMAGE_USER + fb. 


milmg_image *mi_output_image_open( 
miState *state, 
miUint idx) 


>-*Returns an image pointer for a frame buffer index. idx is one of the miRC_IMAGE_RGBA, miRC_ 
IMAGE_USER etc. constants. May only be called from output shaders. Versions prior to 3.4 could 
obtain the output image from a static array in the state, but this array is no longer available in 
mental ray 3.4. This means that all output shaders need to be rewritten for mental ray 3.4. 


void mi_output_image_close( 
miState *State, 
miUint idx) 


°-*Closes an opened frame buffer image that has been opened with mi_output_image_open. idx is 
one of the miRC_IMAGE_RGBA, miRC_IMAGE_USER etc constants. May only be called from output 
shaders. 


miBoolean mi_geoshader_add_result ( 
milag *result, 
const miTag item) 


This function should be called from geometry shaders for adding a scene element to the result. 
If result or item are null, miFALSE is returned. If result refers to a null tag, an instance group is 
created and returned in result. If result is non-null but does not refer to an instance group, an 
instance group is created, the result element is put into this group and the group is returned in 
result. Now that this function has enforced that an instance group element is always returned, 
the ztem element is put into the returned group. See page 283 for an example. 


miBoolean mi_geoshader_tesselate( 


mistate *Sstate, 
miTag *leaves, 
miTag source) 


This function should be called from geometry shaders only. It builds a list of instances that 
describes the object, instance group, or instance source. If source contains more than one object, 
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there will be multiple instances in the leaves list. The leaves argument is set to the tag of the 
first instance; the others are chained to one another with the ext field in each instance. The last 
instance in the list has a null mext field. 


The tessellation function also tessellates the geometry described by each instance, and attaches 
the triangles resulting from the tessellation to the boxes field of the instance. Triangles are stored 
in boxes, which are data structures consisting of a header, a vector list, a vertex list, and a triangle 
list. In mental ray 2.x, boxes have a maximum size; if an object does not fit into one box, more 
are generated and chained using the next_box tag in each box. 


miBoolean mi_geoshader_tesselate_end( 
miTag leaves) 


Release all memory allocated by mi_geoshader-tesselate. This function releases all instances and 
boxes attached to the instance chain /eaves, which was created by mi_geoshader-tesselate. Multiple 
instance lists can exist at the same time; it is not necessary to release one before creating the next but 
since memory demands may be substantial if the tessellated geometry is large, it is recommended 
to not keep instance lists longer than necessary. 


typedef struct { 


miBoolean prefer_approx_polygons; /* triangles from polygons */ 
miBoolean prefer_approx_faces; /* triangles from surfaces */ 
miBoolean ascii_output ; /* non-binary output */ 
miBoolean verbatim_textures; /* dump textures verbatim ? */ 
miBoolean norendercommand ; /* disable rendercmd echo? */ 
miUint explode_objects; /* write objects to subfiles */ 
miTag leaf_insts; /* for prefer_approx_* lookup*/ 
miBoolean nolinkcommand; /* don’t echo link statements*/ 
miUint dont_echo; /*x EO_* bitmap: omit these */ 
miUint dont_recurse; /* EO_* bitmap: no preregs */ 


} miEchoOptions; 


miBoolean mi_geoshader_echo_tag( 
FILE «fp, 
miTag tag, 
miEchoOptions *eopt) 


°*This function exists for debugging geometry shaders. It echos a .mi scene fragment, anchored 
at tag, to the stdio file fp. The options should be cleared with memset or similar, and then 
initialized (the structure occasionally grows; this way recompilation will suffice). The prefer_ 
approx_polygons, prefer_approx_faces, norendercommand, and nolinkcommand must be miFALSE 
(0). ascit_output prints geometry vectors as ASCII numbers instead of the default binary vectors. 
verbatim_textures includes texture files in the echoed scene, instead of referencing them by file 
name. explode-_objects, if nonzero, causes all objects with more than the given number of vectors 
to be echoed to independent subfiles; this is not generally useful for debugging. The dont_echo 
and dont-_recurse bitmaps of miEO_bits allow excluding certain scene element types. In a geometry 
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shader it may be useful to set dont_recurse to ~ 0 to suppress echo of all tags that tag is referencing. 
See the command-line option -echo (appendix A) for more details. 


char *mi_string_substitute ( 


char *newname , 
char *name , 
long size) 


This function? performs substitutions on the file path name, and returns the substituted path in 
newname, which must point to a char buffer of sufficient size (miPATHSIZE is recommended). 
The size of the buffer must be passed as size to prevent buffer overruns. Substitutions are taken 
from the MI_RAY_SUBSTITUTE environment variable, the mental ray registry mechanism, and the 
(obsolete) Softimage Linktab mechanism. For details on the first two refer to [Driemeyer 05]. 
The value of newname is returned. 


miInteger mi_volume_num_shaders ( 
miState *state) 


**In autovolume mode, volume shaders can use this function to determine the number of 
overlapping volumes whose volume shaders have the same (highest) volume level as the current 
volume shader. This is the length of the list of volume shaders to call. Refer to the autovolume 
section on page 253 for more information on autovolumes. mental ray 3.2 also supports 
autovolume mode for photon emitters, so photon shaders can determine which photonvolumes 
a photon passes through. 


miInteger mi_volume_cur_shader ( 
miState *state) 


**Tn autovolume mode, volume shaders can use this function to determine their own position in 
the list of volume shaders to call. The first volume shader gets number 0. 


miTag *mi_volume_tags ( 
miState kstate) 


>-*In autovolume mode, volume shaders can use this function to retrieve the list of volume shader 
tags scheduled for being called for this ray segment. The length of the list can be obtained by 
calling mi_volume_num_shaders. 


miTag *mi_volume_instances ( 
miState *state) 


386 3 Using and Writing Shaders 


°-!'This function is a companion function to mi_volume_tags. It returns a constant pointer to the 
leaf instances through which the current ray is traveling. The n-th instance tag in the returned array 
corresponds to the m-th volume shader tag in the array returned by mi_volume_tags. A volume 
shader could use this function to store the instance it is associated with to state — instance (which 
otherwise holds the instance of the hit primitive) to enable correct object transformations from 
the vector_to_object and point_from_object family. The instance tag can also be used to obtain 
instance-specific user data. 


void mi_opacity_set ( 
miState *State, 
miColor *color) 


>?This function has an effect in rasterizer rendering mode (formerly called Rapid Motion) only. 
Since the rasterizer handles transparency ina separate compositing pass and not inside the material 
shader, the shader cannot normally create matte objects by returning a transparent color regardless 
of other objects behind the shaded surface. The compositing phase would fill in the obscured 
objects. In this case, the shader may use mi_opacity-set to explicitly set the opacity to be used for 
compositing instead oif the result alpha. As a bonus, the opacity may be set for R, G, B, and A 
separately, instead of using the result alpha for all components. The color is saved along with the 
result color returned by the shader until the compositing phase. 


miBoolean mi_opacity_set ( 
miState *otate, 
miColor *color) 


>? After mi_opacity-_set has been called at any point for the current surface shading point and all 
its secondary rays, it remains in effect until the rasterizer (formerly called Rapid Motion) shades 
the next surface point. It is saved along with the returned color until compositing. Since any of 
the shaders of a Phenomenon can call mi_opacity-_set, the companion function mi_opacity_get can 
be used to retrieve the opacity color last set. This is also useful in volume shaders that need to 
control matte opacity. The function returns miFALSE if m1_opacity_set has not been called for the 
current shading point yet; in this case color is undefined. 


miColor *mi_volume_user_color( 
miState *State) 


In autovolume mode, volume shaders can use this function to store an arbitrary color value. 
This is useful for communication between different volume shaders in the list. For example, the 
first volume shader can initialize this value, and the last can return it. 
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3.26.13. Multipass Rendering Functions? 


void *mi_renderpass_access( 


misState *State, 
int pass, 
int fb) 


>-l' This function is used by multipass rendering merge functions*'! to retrieve a pointer to sampling 
data. The merge function is called once for each sample, and has to merge all render pass samples 
for the same coordinate into the result sample. The pass argument is -1 for obtaining a pointer 
to the result sample, or 0...state — options — npasses — 1 for obtaining a pointer to the sample 
rendered in that pass. If a null pointer is returned, the pass did not cast this sample; this happens 
only if the corresponding area of the pass image is completely blank or the frame buffer specified 
by fb was not rendered. (The shader may assume an all-null sample in this case.) The fb argument 
specifies the frame buffer to access, and must be one of the miRC_IMAGE_* macros. miRC_IMAGE_ 
RGBA and miRC_IMAGE_Z are always available; others may return 0. 


miBoolean mi_renderpass_sample_get ( 


void *result, 
int resultsize, 
misState *State, 

int Lb, 

int ae 

int y) 


This function is intended exclusively for multipass preprocessing functions. It returns the 
sample data from a single frame buffer fb at the specified sample coordinate x, y. The sample is 
copied to result. At most resultsize bytes are copied. For example, if fb is miRC_IMAGE_RGBA, result 
should be a pointer to a miColor and resultsize should be sizeof(miColor). Since miRC_IMAGE_ 
RGBA is always the first frame buffer, it is possible to copy the entire sample by specifying a larger 
resultsize. A size that is too large will be truncated to the actual sample size. This assumes that 
the prep shader knows the actual sample layout, which makes such a shader nonportable to other 
projects. The imf_info -m command-line tool can be used to determine the sample layout of a 
pass sample file. 


miBoolean mi_renderpass_sample_put ( 


void *result, 
IG resultsize, 
miState *State, 

int Tt, 

int x. 

int y) 


>This function is intended exclusively for multipass preprocessing functions. It is the reverse 
function to the previous, and writes a sample to the output pass file. Written samples cannot be 
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read again; the get and put functions access different pass files according to the read and write 
file names specified in the pass prep statement in the options block. 


mi_renderpass_resolution( 


int *x1, 
int *yl, 
int *XS, 
int *YS, 
int *xres, 
int *yres, 
miState *State, 
int < 

int y) 


°!'This function is intended exclusively for multipass preprocessing functions. It returns 
information about the rectangle that the sample coordinate x, y is in. Pass files are organized 
in the same rectangles that become visible as rendering units when attaching the zmf_disp tool to 
a running mental ray render. They generally have a fixed size depending on oversampling, but 
may be smaller or larger near the edges of the image. The lower left sample coordinate x/, yl, 
the rectangle size in samples xs, ys, and the resolution of the entire image in samples xres, yres is 
returned. Any of these pointers may be null if the corresponding count is not needed. Note that 
rectangles may overlap. It is often useful to consider rectangles when preprocessing even though 
the get and put functions seem sufficient, because the following flush and black functions allow 
optimizations based on rectangles. 


miBoolean mi_renderpass_samplerect_flush( 


miState *State, 
int pass, 
int as 

int y) 


°-'This function is intended exclusively for multipass preprocessing functions. If applied to the 
read pass file (pass is 1), this announces that the rectangle that the coordinate x, y is in will not be 
read from for a while, which removes it from the cache. If applied to the write pass file (pass is 
0), this announces that the prep shader is definitely finished with writing this rectangle. It is ok 
to read again from a flushed rectangle, but writes to flushed rectangle will be ignored and must 
be avoided. The flush function reduces the memory required for preprocessing a pass file. 


miBoolean mi_renderpass_samplerect_black ( 


miBoolean *result, 
misState *state, 
Lut as 


int y) 
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>This function is intended exclusively for multipass preprocessing functions. It returns mi TRUE 
if all samples in the rectangle that the coordinate x, y is in are entirely black (all null bytes). Calling 
this function can avoid a lot of unnecessary computation in the prep shader. 


3.26.14 Obsolete Auxiliary Functions 


These functions are obsolete; use mi_query for future implementations. 


void mi_light_info( 


miTag tag, 
miVector *org, 
miVector *dir, 
void *kparas ) 


tag is assumed to be a light source instance as found in a light parameter of a shader, or returned 
by mi_query. It is looked up, and its origin (location in internal space) is stored in *org, and its 
direction (also in internal space) is stored in *dir. If tag refers to a light source instead of the 
instance, both vectors are defined in local space. Since light sources can only have one or the 
other but not both, the unused vector is set to a null vector. This can be used to distinguish 
directional (infinite) light sources; their org vector is set to (0,0,0). The paras pointer is set to 
the shader parameters of the referenced light shader; if properly cast by the caller, it can extract 
information such as whether a non-directional light source is a point or a spot light, and its color 
and attenuation parameters. (mental ray considers a spot light to be a point light with directional 
attenuation.) Any of the three pointers org, dir, and paras can be a null pointer. 


int mi_global_lights_info( 
miTag *ktag) 


Returns the address of an array containing all global light leaf instances. The tags in this array can 
be used like light shader parameters for calls to mi_sample_light and mi_light_info. One important 
difference between shader light parameters and global lights is that global lights are the result 
of instancing, so if a light is transformed and/or multiply instanced it will appear transformed 
and/or more than once in the global light list, while shader parameters will be accessed as stored 
in the scene with no instancing applied. It is recommended that translators that support multiple 
light instancing use material shaders that use the global light list instead of a light array in the 
shader parameter list (which, however, may still be useful as an argument for mi_inclusive_lightlist 
and mi_exclusive_lightlist). 


void mi_texture_info( 


miTag tag, 
int *xres, 
int *yres, 


void *kparas ) 


390 3 Using and Writing Shaders 


tag is assumed to be a texture as found in a texture parameter of a shader. If tag refers to a 
procedural texture shader, *xres and *yres are set to 0 and *paras is set to the shader parameters 
of the texture shader. If tag is an image texture, *xves and *yres are set to the image resolution in 
pixels, and *paras is set to 0. Any of the three pointers can be a null pointer. 


void *mi_shader_info( 
miState *State) 


Returns a pointer to the user pointer of the current shader in the state, state — shader. This is 
useful for shaders that allocate memory during startup (in the instance init shader) and need a 
place to store the pointer to the initialized data in a place where shader instances can pick it up. A 
unique user pointer is returned for each shader instance (each unique function/parameters pair). 


int mi_instance_info( 
miState *Sstate, 
void ** const paraspp, 
void ** const sparel, 
void ** const spare2, 
void ** const spare3) 


Returns the size of and a pointer to the inherited instance parameters. Instance parameters are 
attached to the instances of the scene DAG, and are combined ina scene DAG traversal step during 
scene preprocessing, before rendering begins. The structure of the inherited data is determined by 
the inheritance function or traversal function®"', not by the shader, and is generally under control 
of the translator that generated the scene. Typically, all instances contain either no parameters at 
all (size 0), or they all use the same data structure. The instance being checked is state — instance. 
The spare pointers must be passed as 0. 


3.26.15 Contour Functions 


miBoolean mi_get_contour_line( 
miContour_endpoint *p1, 
miContour_endpoint *p2) ; 


This function can be used by a contour output shader to get end points of a contour line segment. 
When mi_get_contour_line returns miFALSE, there are no more contour lines. 


void mi_add_contour_lines( 
miContour_endpoint pi[], 
miContour_endpoint p2[], 
int BJ; 
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This is another function available to contour output shaders. It adds extra contour lines to the 
ones that were found during rendering. p/ is the list of first endpoints, p2 is the list of second 
endpoints, and 7 is the number of contour lines to be added (the number of elements in the lists). 
This can for example be used by a combination of two contour output shaders: the first one adds 
some extra contour lines, and the second one renders all contour lines (both the contour lines 
found during rendering and the extra contour lines added using mi_add_contour_lines). Or, as 
another example, the first contour output shader can read all contour lines, analyze them, and 
write back a subset of them (or even some altogether different contours) with mi_add_contour- 
lines. 


3.26.16 Light Map Functions 


miImg_image *mi_lightmap_edit ( 
void *xkhandle, 
miTag tag) 


This function is used by lightmap shader to begin writing to the writable texture tag. It must have 
been defined in the scene with the writable keyword and was probably passed to the lightmap 
shader using a texture parameter. This function clears the texture, and returns an image pointer 
that can be used to write pixels with functions like m1img_put-_color. The handle is returned as 
an opaque pointer that should be passed to mi_lightmap_edit_end. 


void mi_lightmap_edit_end( 
void *handle) 


Completes writing to the writable texture handle, which must have been previously created with 
mi_tlightmap-edit. The texture is written to disk. 


3.26.17, Memory Allocation 


mental ray’s memory allocation functions replace the standard malloc packages found on most 
systems. They have built-in functions for memory leak tracing and consistency checks, and handle 
errors automatically. Shaders should always use these functions and not malloc or similar libc 
functions directly. 


void *mi_mem_allocate( 
const int size) 


Accepts one argument specifying the size of the memory to allocate. A pointer to the allocated 
memory is returned. If the allocation fails, an error is reported automatically, and mental ray tries 
to recover memory or aborts if this fails. This call is guaranteed to return a valid pointer, or not to 
return at all. The allocated memory is zeroed. This and most other mem-_* functions use locking 
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and should therefore not be used in time-critical places to prevent multithreading efficiency from 
dropping through the floor. See page 394 for details on the effect of locks on efficiency. A good 
place for memory allocation is init shaders. 


void *mi_mem_reallocate( 
void * const men, 
const int size) 


Changes the size of an allocated block of memory. There are two arguments: a pointer to the 
old block of memory, and the requested new size of that block. A pointer to the new block is 
returned, which may be different from the pointer to the old block. If the old pointer was a 
null pointer, 7z_mem_-reallocate behaves like mi_mem_allocate. If the new size is zero, mi_-mem_ 
reallocate behaves like mi_mem_release, and returns a null pointer. If there is an allocation error, 
an error is reported and raylib is aborted. Like mi_mem_allocate, mimem_reallocate never returns 
if the re-allocation fails. If the block grows, the extra bytes are zeroed. 


void mi_mem_release( 
void * const mem) 


Frees a block of memory. There is one argument: the address of the block. If a null pointer is 
passed, nothing is done. There is no return value. After releasing memory it may no longer be 
accessed. 


char *mi_mem_strdup( 
const char *text) 


Allocates enough memory to hold text including the trailing null byte, copies text into the 
allocated memory, and returns it. The returned string must be released with mi_mem_release. 
This function is especially useful to pass strings to functions in the mi_api_ family, which all 
expect allocated strings (and will automatically handle the required mi_mem_release). 


3.26.18 Thread Parallelism and Locks 


In addition to network parallelism, mental ray also supports shared memory parallelism through 
threads. Network parallelism is a form of distributed memory parallelism where processes 
cooperate by exchanging messages. Messages are used to exchange data as well as to synchronize. 
With shared memory data can easily be exchanged, a process must only access the common 
memory to do so. A different mechanism has to be used for synchronization. This is usually done 
by locking. Basically what has to be done is one process has to tell the other that it is waiting to 
access data, and another process can signal that it has finished working with it, so that any other 
process may now access it. 
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By default threads are used on shared memory multiprocessor machines. Threads are sometimes 
also called lightweight processes. Threads behave like processes running on a common shared 
memory. 


Since memory is shared between two threads, both can write to memory at the same time. It can 
also happen that one thread writes while another reads the same memory. Both these cases can 
lead to surprising unwanted results. Therefore — to guard against these surprises — when using 
threads certain precautions have to be observed. Care has to be taken when using heap memory 
such as global or static data, as any thread may potentially modify it. To prevent corrupting any 
data (or reading corrupted data), locking must be used when it is not otherwise guaranteed that 
concurrent accesses will not occur. The stack, however, is always safe because every thread has 
its own stack that is not shared with any other thread. 


In addition to making sure that write accesses to data are performed when no other thread 
accesses the data, it is important to use only so-called concurrency safe libraries and calls. If a 
call to a nonreentrant function is done, locking should be used. A function is called reentrant 
if it can be executed by multiple threads at the same time without adverse effects. (Reentrancy 
and concurrency safety are related, but the terms stem from different historical contexts, and 
reentrancy also implies the ability to recurse safely.) Details and examples are explained below. 


For example, static data on a shared memory multiprocessor can be modified by more than one 
processor at a time. Consider this test: 


static miBoolean is_init = miFALSE; 


af) Ciiadnit) .f 
is_init = miTRUE; 
initialize(); 


This does not guarantee that initialize is called only once. The reason is that all threads share the 
is_init flag, so two threads may simultaneously examine the flag. It is possible that both will find 
that it has not been set, and enter the if body. Next, both will set the flag to mi TRUE, and then both 
will call the zmztialize function. This situation is called a race condition. The example is contrived 
because initialization and termination should be done with init and exit shaders as described in 
the next section, but this problem can occur with any heap variable. Even incrementing global 
or static variables with “++” is not safe — the time window that leads to errors may be small, but 
that makes such mistakes all the more difficult to find. In general, all threads on a host share all 
data except local auto variables on the stack. 


The behavior described above could also occur if more than one thread is used on a single 
processor, but by default mental ray does not create more threads than there are processors. 


There are two methods for guarding against race conditions. One is to guarantee that only one 
thread executes certain code at a time. Such code surrounded by lock and unlock operations is 
called a critical section. Code inside of critical sections may access global or static data or call any 
function that does so (as long as all is protected by the same lock). The lock used in this example 
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is assumed to have been created and initialized with a call to mi_init_lock before it used here. (See 
below how locks are initialized.) Here is an example of how a critical section may be used: 


miLock lock; 


mi_lock(lock) ; 

if €is init) + 
is_init = miTRUE; 
initialize(); 

} 


mi_unlock(lock) ; 
The other method is to use separate variables for each thread. There are two places available: 


e data attached with the miQ_FUNC_USERPTR mode of mi_query is separate for each shader 
instance. This is useful for preprocessing shader parameters. 


e data attached with the thread local shader storage facility is shared by all instances of a 
shader, but is kept separate from simultaneous accesses by other threads so no locks are 
required. 


Up to mental ray 2.1, it was possible to use the mi_par_nthreads function to allocate an array that 
can be indexed with the thread number, but in mental ray 3.x this is no longer possible because 
the number of threads has become dynamic and may change at any time, regardless of what 
number of threads was set with the -threads command-line option. The limit of 1024 threads 
was removed in mental ray 3.1. 


See the section on Persistent Shader Data Storage on page 406 for more details on lock-free shader 
data storage. 


Allocation is done in the initialization function (which has the same name as the shader with _ 
init appended) of the shader or shader instance. No locking is required because it is called only 
once. The termination function (which also has the same name but with _exit appended) must 
release the data. 


Locks reduce multithreading efficiency and should be used only when absolutely necessary, or 
in shader initialization functions, which are called only rarely. The probability of one thread 
blocking because another has locked a section of code grows very quickly with the number of 
threads, and a thread that is blocked is not available to do useful work. Efficiency describes the 
degree of parallelism: if 7 threads increase the speed by a factor m, then the efficiency is “. If two 
threads have an efficiency of 0.95, then 32 threads have an efficiency of only 0.95°* = 0.19, so over 
80% of all CPU cycles are wasted! Efficiency drops surprisingly quickly, so careful attention to 
locks is required. Note that memory allocation and releasing functions (mi_mem_allocate et. al.) 
contain a lock. 


mental ray provides two locks for general use: state—global_lock is a lock shared by all threads 
and all shaders. No two critical sections protected by this lock can execute simultaneously on 
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this host. The second is the shader lock, a pointer to which can be obtained with the miQ_FUNC_ 
LOCK mode of mi_query, which is local to all instances of the current shader: 


miLock *lock; 
mi_query(miQ_FUNC_LOCK, state, miNULLTAG, &lock); 
mi_lock(*lock) ; 


mi_unlock(*lock) ; 


The lock is tied to the shader, not the particular call with particular shader parameters. Every 
shader in mental ray, built-in or dynamically linked, has exactly one such lock. mental ray 
internally uses this lock and the global lock to guarantee that the init and exit shaders of a shader 
do not execute concurrently. Therefore, they must not be used in these functions. 


The relevant functions provided by the parallelism modules are: 


miBoolean mi_init_lock( 
miLock * const lock) 


Before a lock can be used by one of the other locking functions, it must be initialized with this 
function. Note that the lock variable must be static or global. Shaders will normally use this 
function in their _27zt function. Shaders should not initialize (or delete) state — global_lock or 
the local shader lock; they are pre-initialized by mental ray. The function returns miFALSE if the 
operating system failed to create the lock. 


void mi_delete_lock( 
miLock * const lock) 


Destroy a lock. This should be done when it is no longer needed. The code should use lock and 
immediately unlock the lock first to make sure that no other thread is in or waiting for a critical 
section protected by this lock. Shaders will normally use this function in their exit shader. Do 
not delete the predefined locks. 


void mi_lock( 
const miLock lock) 


Check if any other code holds the lock. If so, block; otherwise set the lock and proceed. This 1s 
done in a parallel-safe way so only one critical section locked can execute at a time. Note that 
locking the same lock twice in a row without anyone unlocking it will block the thread forever, 
effectively freezing mental ray, because the second lock can never succeed. 


void mi_unlock( 
const miLock lock) 
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Release a lock. If another thread was blocked attempting to set the lock, it can proceed now. 
Locks and unlocks must always be paired, and the code between locking and unlocking must be 
as short and as fast as possible to avoid defeating parallelism. There is no fairness guarantee that 
ensures that the thread that has been blocked for the longest time is unblocked first. 


miVpu mi_par_localvpu(void) 

int miTHREAD(miVpu vpu) 

int miHOST(miVpu vpu) 

miVpu miVPU(int host, int thread) 


*-1The term VPU stands for Virtual Processing Unit. All threads on the network have a unique 
VPU number. mi_par_localvpu*' returns the VPU number of the VPU this thread is running on. 
VPUs are a concatenation of the host number and the thread number, both numbered from 0 to 
the number of hosts or threads, respectively, minus 1. (Future versions of mental ray may use 
noncontiguous host numbers, but not noncontiguous thread numbers.) 


The miTHREAD?! macro extracts a thread number from a VPU, and the miHOST?:! macro 
extracts the host number from a VPU. Thread 0 is called the master thread; host 0 is called 
the master host. Thread 0 on host 0 is normally running the translator that controls the entire 
operation. The miVPU?"' macro puts a host and thread number together to form a VPU number. 
The mi_par_tlocalvpu function returns the VPU of the current thread on the local host. 


In a shader the fastest way of finding the current thread number is state — thread. This is the 
only thread function still available in mental ray 3.x. Otherwise mental ray 3.x does not have 
mental ray 2.1’s fixed notion of VPUs and threads; they come and go. 


int mi_par_nthreads (void) 


*-!Returns the number of threads on the local host. This is normally 1 ona single-processor system. 
This number can be used to allocate an array of per-thread variables in the shader initialization 
code. The array can then be indexed by the shader with state — thread. mental ray 3.x does 
not have the notion of a fixed number of threads and therefore does not support this function. 
For backwards compatibility the function exists, but it always returns 65. This is obviously not 
something a shader should rely on but it may keep some older shaders limping along until they 
are ported. Do not use! 


int mi_par_aborted (void) 


Return a nonzero value if mental ray has been aborted, and the shader should stop what it is 
doing, clean up, and return. This is only of interest in output shaders because they can run for a 
long time. This allows the user to press on an abort button, which causes calls to mi_par_aborted 
to return nonzero, and have the shader return as soon as possible. For example, the shader might 
call this function in its scanline loop (not for every pixel to avoid slowing it down), and skip 
the remaining lines. The shader must still clean up, for example releasing memory that it has 
allocated. 
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long mi_job_memory_limit ( 
long limit, 
long vlimit) 


*-*Set the size of mental ray’s memory cache to limit bytes, and the virtual address space cache 
limit for memory-mapped textures to vlimit bytes. Both are separate and independent. mental 
ray’s memory manager will attempt to keep these limits by evicting data that can be restored if 
necessary to maintain these limits. A good v/imit is a quarter of the address space of the machine 
(the default is 1 gigabyte). A good /imit is one half of the machine’s physical memory (the default 
is unlimited for mental ray 3.0 and 512 megabytes for mental ray 3.1 and later). Values of 0 mean 
“unlimited”, and values of -1 mean “don’t change”. If caches are too small, mental ray will begin 
to thrash or fail to maintain the limits; this is evident from the garbage collection messages printed 
if the verbosity level (-verbose command-line option) is at least 4. 


mental ray 3.2 no longer supports this function. It was replaced with mimem_memory_limit. 


miUlong mi_mem_memory_limit ( 
miUlong limit) 


>-27 imit the total heap size used by mental ray allocations to limit bytes. Unlike the older mi_job_ 
memory_limit, this does not only limit the size of the geometry cache, but all memory allocations 
performed by mental ray. It can no longer happen that some large memory user can crowd out 
the geometry cache; everything is subject to flushing and re-using now. 


Operating system memory usage is not included, however. This means the program itself, any 
shared libraries (DSO or DLL), thread stacks, and reserved kernel memory. Also, if mental ray 
is linked into some other application, memory allocations performed by that application are 
not included either. In practice, this leaves about 1.3 GB on 32-bit systems except Windows 
Professional Server (not regular Windows), which allows 3 GB, and Linux, which allows almost 
4 GB. The memory limit defined by this function should stay comfortably below this limit, by 
a hundred megabytes or more, depending on what else is going on in the system. It should also 
stay well below the amount of physical RAM minus OS usage, even on 64-bit systems, to avoid 
kernel swapping. 


3.26.19 Messages and Errors 


Shaders may print messages and errors. They are printed in the same format as rendering (RC) 
messages. Options given to the translator determine which messages are printed and which are 
suppressed. All message routines have the same parameters as printf(3). All append a newline to 
the message. Messages are printed in the form 


RC host.thread level: message 


with the module name, e.g. RC, the host number host if available, the thread number thread with 
a leading dot if available, the message type /evel (fatal, error, warning etc), and the message given 
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in the function call. In a networked environment, the messages of slaves are usually transferred to 
the master rendering host and printed in the order they were received. Messages resulting from 
connection problems and those that were dropped to avoid a network overload may be found in 
a local file (/tmp/raylib.1log). Newlines in the message are replaced with blanks. 


void mi_fatal( 
const char * const message, 


“ 


An unrecoverable error has occurred. Unlike all others, this call will not return; it will attempt 
to recover mental ray and return to the top-level translator. Recovering may involve aborting all 
operations in progress and clearing the entire database. Fatal messages can be suppressed, but 
mental ray is always exited. This function should never be used in a shader because it may also 
exit any application that mental ray is embedded in, without giving the user a chance to save his 
work! 


void mi_error( 
const char * const message, 


id 


An unrecoverable error has occurred. The caller then aborts the current operation gracefully and 
returns. 


void mi_warning ( 
const char * const message, 


“ 


A recoverable error occurred. The current operation proceeds. 


void mi_info( 
const char * const message, 


- 


Prints information about the current operation such as the number of triangles and timing 
information. Infos should be used sparingly; do not print information for every intersection 
point or shader call except during debugging, especially on Windows NT 4.x with its slow and 
nonparallel I/O system. 


void mi_progress ( 
const char * const message, 


“J 
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Prints progress reports such as rendering percentages. 


void mi_debug( 
const char * const message, 


2 
Prints debugging information useful only for shader development. 


void mi_vdebug( 
const char * const message, 


stig 


Prints more debugging information useful only for shader development. Messages that are likely 
to be useful only in rare circumstances, or that generate a very large number of lines should be 
printed with this function. 


Note that all these functions incur some runtime overhead even if the verbosity level is set such 
that no message is printed. It is often a good idea to enclose shader debugging messages that occur 
frequently in ifdef DEBUG statements to make sure they are omitted in production versions of 


the shader. 


3.26.20 Callable Functions by Shader Type 


The following table describes which shader interface functions are available in which types of 
shaders. Shader types are abbreviated: 


geometry shader 

displacement shader 

photon shader and photon volume shader 
photon emitter shader 

lens shader 

material shader and texture shader 

volume shader 

light shader 

shadow shader 

contour store shader 

contour contrast shader and contour shader 
output shader and multipass rendering merge function” 
lightmap shader?* 

state shaderstate shader?” 


a es a aa oS 


ie je) 


1 


ErOADe 


The rules for init shaders and exit shaders are the same as for the main shader they apply to. In 
the table, “e” means that the function may be used, “o” means that it may not be used, and “x” 
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means that it is available but is not normally useful. The asterisk “*” denotes omission unless an 
earlier more specific table row overrides it. For example, mz_eval* means all functions beginning 
with mi_eval, including mi_eval itself, mi_eval_boolean, and so on. 


function ——S*=—“—*~*S*S*~*~CSS@SPCOE *Se MV gS GC O Im& 


Shader Calls 
mi_call_shader* 
mi_call_material 
mi_call_photon_material 
mi_eval* 

mi_flush_cache 


RC Functions 
mi_trace_eye 
mi_trace_reflection 
mi_trace_refraction 
mi_trace_transparent 
mi_trace_environment 
mi_trace_probe 
mi_trace_light 


mi_sample_light 
mi_trace_shadow 
mi_trace_shadow-_seg 
mi_inclusive_lightlist 
mi_exclusive_lightlist 
mi_compute_irradiance 

irradi backside** 
mi-compute-_irradiance_backside 


mi_compute_avg_radiance*? 


mi_compute_volume_irradiance 
mi-_compute-_directional_irradiance 
mi_sample 

RC Photon Functions 
mi_photon_light 
mi_photon_reflection_specular 
mi_photon_reflection_glossy 
mi_photon_reflection_diffuse 
mi_photon-_transmission_specular 
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ia 
mi_photon_transmission_glossy 
mi_photon_transmission_diffuse 
mi_photon_transparent 
mi_photon_volume-scattering 
mi-_store_photon 
mi_store_volume_photon 

RC Direction Functions 
mi_reflection_dir 
mi_reflection_dir_specular 
mi_reflection_dir_glossy 
mi_reflection_dir_anisglossy 
mi_reflection_dir_diffuse 
mi_refraction_dir 
mi_transmission_dir_specular 
mi_transmission_dir_glossy 
mi_transmission_dir_anisglossy 
mi_transmission_dir_diffuse 
mi_scattering_dir_diffuse 
mi-_scattering_dir_directional 
mi_scattering_pathlength 
IMG Functions 
mi_img_put_* 

mi_img_get_* 
mi_img_tonemap 

Math Functions 
mi_point_to_* 
mi_point_trom_* 
mi_vector_to_* 
mi_vector_from_* 
mi_normal_to_* 
mi_normal_from_* 
mi_vector_* 

mi_matrix_* 

mi_point_* 

Noise Functions 
mi_par_random 

mi_*random 

mi_spline 

mi_noise_* 

mi_unoise_* 


Color Profile Functions’ 
mi_colorprofile_* 


Auxiliary Functions 


00000 016 
oo 6 6 6 610 
ee3eee ely 
0° 0000 O|]fF; 
09000 O}& 
0000 0 O]< 
00000 O1[W 
eo oy bo ory 
00000 01/6 


-s FF FF FF FF FF SF FS 
oeoeeeeeeeee§eeeee ®e 
@oeoeeeeeeeeeee e 
@®oeeeeeee#eeeeese ®@ 
@oeoeeeeeeeeeereeese ®@ 
oeoeeeeeeeeeee ®@ 
@oeoeeeeeeeeeeeeres ®@ 
@oeeeeeeeeeee ®e 
@oeeeeeeeeeeeese ®@ 
@oeeeeeeeeeseeee ®@ 
@oeeeeeeee#eeseee ®@ 
> © See RF SE HF SE HS HY 
®oeoeeeee#eeesereeeeee e 
Go Oo OO Oo OF Oo OO "OO Oo 


® @@ 00 0 0 0 0 
@oeoeoeeeeee e 
@oee#eeeeeeee ® 
eoeoeoe#eeeeeee ®@ 
@oeeeee88@86@686UctmUlCUM® 
@oeeeoeeeee ®e 
®eeeeeees ®@ 
eoeeoeeeeee e 
© eeeeeee ®e 
oeoeeeeeeeoees ®@ 
eo e@2eeeeees ® 
® @e@o0oo0o9090 0 0 
@oeoeeeee e® ® 
oeeeeeesee ®@ 


402 3 Using and Writing Shaders 


in 
mi_fresnel 
mi_tresnel_reflection 
mi_phong-specular 
mi_tresnel_specular 
mi_blinn_specular 
mi_blong_specular 
mi_cooktorr_specular 
mi_ward_glossy 
mi_ward_anisglossy 
mi-_schlick_scatter 
mi_choose-scatter_type 
mi_choose-_simple-_scatter_type 
mi_choose-_lobe 

mi_luminance 
mi_lookup_*_texture 
mi_texture_filter_project 
mi_texture_filter_transform 
mi_tri_vectors 

mi_query 
mi_shaderstate_-enumerate 
mi_shaderstate_set?* 
mi_shaderstate_get?? 
mi_tb_put 

mi_tb_get 
mi_output_image_open 
mi_output_image_close 
mi_geoshader_add_result 
mi_geoshader-_tesselate 
mi_geoshader_tesselate_end 
mi_geoshader_echo_tag?* 
mi-_string_substitute 
mi_volume_num_shaders?* 
mi_volume_cur_shader** 
mi_volume_tags°* 
mi_volume_user-_color?* 


Obsolete Aux. Functions 
mi_* _info 


Contour Functions 
mi-_get_contour_line 
mi_add_contour_lines 


Dee 
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Light Mapping Functions 
mi_lightmap_edit** 
mi_lightmap_edit_end°* 
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function 633) ad eid Lie AML MV ey 9 fag hs 42 ne 


Memory Allocation 
rime ht tee 5 edness ai 
Thread Parallelism, Locks 
mi_init_lock 
mi_delete_lock 

mi_lock 

mi_unlock 
mi_par_localvpu?'! 
mi_par_nthreads?"! 
mi_par_aborted 

Messages and Errors 
mi_tatal 

mi_error 

mi_warning 

mi_into 

mi_progress 

mi_debug 

mi_vdebug 


See page 224 for a similar table listing available state variables. 


3.27 Initialization and Cleanup 


mental ray provides a way to define initialization and cleanup functions for each user defined 
function. Many shaders need to perform operations such as initializing color tables or allocating 
arrays before they are called for the first time. They may also need to do cleanup operations after 
rendering has finished, for operations like releasing storage to prevent memory leaks. 


Before a shader is called for the first time, ray checks if a function of the same name with _init 
appended exists. If so, it assumes that this is an initialization function (also called zit shader ) and 
calls it once before the first call of the shader. The state passed to the initialization function is the 
same as passed to the first call of the actual shader to be initialized. Note that the order of shader 
calls is unpredictable because the order of pixel samples is unpredictable, so the initialization 
function should not rely on sample-specific state variables such as state—point. It may also not 
perform any operations that cause other shaders to be called, such as tracing a ray. 


The initialization function has the option of requesting shader instance initializations by setting 
the boolean variable that its third argument points to to miTRUE. A shader instance is a unique 
pair of shader and shader parameters. For example, if the shader mib_illum_phong is used in two 
different materials it is said to have two different instances (even if the parameter values happen 
to be equal). When an init shader is called as part of the shader instance initialization, it receives 
the same parameters that the main shader will receive. As always, shaders may not write back 
into their shader parameters because that confuses other threads or hosts that access the shader 
simultaneously, because it changes the scene for the next frame, and because a shader or interface 
assignment may get mangled. 
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When a rendering phase has finished, mental ray checks for each user provided shader that was 
called whether a function of the same name with _exit appended exists. If yes, it assumes that 
this is a cleanup function and calls it once. For example, if a shader myshader exists, the functions 
myshader_init and myshader-_exit are called for initialization and cleanup if they exist. The exact 
time the exit function is called depends on the rendering phase: geometry shaders are exited 
when preprocessing has finished; most other shaders are exited when the frame has finished on 
the master host or after each rectangle has finished on slave host (slaves do not manage entire 
frames, they contribute individual rectangles only). Exit functions cannot be used to detect end 
of rendering, use an output shader or a call statement for that. 


The functions are assumed to have the following type: 


void myshader_init(miState *state, 
void *paras, 
miBoolean *inst_init_req) ; 


void myshader_exit(miState  ¥*state, 
void *paras) ; 


The -i option of the mkmishader utility automatically creates init and exit shader prototypes. 
Here is an example for init and exit shaders for a shader named myshader. When myshader is 
about to be used for the first time in a frame, the calling order is: 


1. myshaderinit with a null paras argument 
2. myshaderinit with non-null paras argument 
3. myshader itself with the same non-null paras argument 


4. more calls to myshader with the same paras argument, and calls to other instances of 
myshader_init and myshader with different paras arguments, 


5. one mi_shader_exit with a non-null paras argument for each corresponding myshader_init 


6. finally one myshader_exit with a null paras argument. 


Steps 2 and 5 would have been omitted if myshader_init in step 1 had not set its third argument zmst_ 
req to miTRUE. Two different instances of the same shader always have different paras argument 
pointers. However, a shadow or photon shader and a material shader in the same material may 
share parameters as described above; in this case both shaders are called with the same paras 
argument. Most scenes are built this way, it is recommended to write material shaders so they can 
also be used as shadow and photon shaders to simplify scene construction. 


DLLEXPORT void myshader_init( /* must end with "_init" */ 
miState *state, 
struct myshader *paras, /* valid for inst inits */ 
miBoolean *xinst_req) /* for inst init request */ 
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1: 
if (!paras) { /* main shader init */ 
*inst_req = miTRUE; /* want inst inits too */ 
+} else { /* shader instance init */ 
/* just an example: */ 
void **user; 
mi_query(miQ_FUNC_USERPTR, state, 0, user); 
*user = mi_mem_allocate(...); 
} 
} 
DLLEXPORT void myshader_exit( /* must end with "_exit" */ 
miState *State, 
struct myshader *paras) /* valid for inst inits */ 
{ 
if ('paras) { /* main shader exit */ 
/* no further inst exits 
* will occur */ 
+} else { /* shader instance exit */ 
/* just an example: */ 
void **user; 
mi_query(miQ_FUNC_USERPTR, state, 0, kuser); 
mi_mem_release(*user) ; 
} 
} 


Note that there will generally be many instance init/exits (if enabled), but only one shader 
init/exit. If an init/exit shader is not available, it is not called; this is not an error. Initialization and 
cleanup are done on every host where the function was used, but only once on shared memory 
parallel machines. They are done for each frame separately. Init and exit shaders will never run 
concurrently with each other or the actual shader on shared-memory multiprocessor machines; 
mental ray takes care of the appropriate locking using the shader lock. For this reason, init and 
exit shaders should never lock the shader lock (obtainable with the miQ_FUNC_LOCK mode of the 
mi_query function) because that would deadlock mental ray. 


Note that mental ray 2.x had a state variable state — shader — user.p that contained the user 
pointer user above, with no need for calling mi_query. This variable no longer exists in mental 
ray 3.x because the dataflow architecture of mental ray 3.0 cannot permit shaders to write back 
into the scene. Such a write might be lost at any time if mental ray decides to temporarily drop 
elements from its geometry cache. The mz_qguery method is recommended because it works with 
both 2.1 and 3.0. This is one of the two main incompatibilities between mental ray 2.1 and 3.0. 
(The other is that the number of threads is no longer fixed.) 
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3.28 Persistent Shader Data Storage 


Shaders often need to store data persistently. Init shaders may construct tables, preprocess 
parameters, or prepare other data that is common to all future shader calls and can be done 
once, in advance, instead of repeating the computation for every shader call. This can improve 
performance significantly if a shader is called millions of times for rendering a frame. There are 
three classes of storage: constant data, per-instance data, and per-thread data. 


3.28.1 Constant Data 


If the data is constant, such as a random number lattice for Perlin noise functions, it can be stored 
in a static array that is built in the init shader and deleted, if necessary, in the exit shader. 


static struct mystruct *mydata; 


DLLEXPORT void myshader_init ( /* init shader */ 
miState *state, 
struct myshader *paras, 
miBoolean *inst_req) 

{ 


mydata = mi_mem_allocate(...) 
.initialize *mydata... 


return (miTRUE) ; 
} 
DLLEXPORT void myshader_exit ( /* exit shader */ 
miState *state, 
struct myshader *paras) 
{ 
mi_mem_release(mydata) ; 
return (miTRUE) ; 
} 
DLLEXPORT void myshader ( /* main shader */ 
miState *state, 
struct myshader *paras) 
{ 
..read-only access to *mydata... 
return (miTRUE) ; 
t 


This form of data storage is very simple, but can be used only if the data is constant for the current 
frame, and does not in any way depend on shader parameters or the shader instance. This means 
that the shader body may not modify the data because it is unpredictable in which order shaders 
are called. Worse, the shader may be called in multiple threads simultaneously, so writing to the 
data could become interleaved in ways that are very hard to reproduce and debug. Locking is not 
a solution because that would mean that shaders would have to “wait in line” to gain access to 
the data, which seriously degrades parallel performance. 
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3.28.2 Shader Instance Data 


If the data is separate for each shader instance, it can be created in the init shader and attached to 
the shader instance itself. This is the recommended method for preprocessing shader parameters 
into a form that simplifies later shader calls during rendering. For example, if a shader parameter 
specifies an angle in radians or degrees, converting the angle to the cosine of the angle once in 
advance can save millions of expensive cosine computations in the main body of the shader. Here 
is an example: 


DLLEXPORT void myshader_init ( /* init shader */ 
miState *State, 
struct myshader *paras, 
miBoolean *inst_req) 

{ 


if (!paras) 
*inst_req = miTRUE; 
else { 
struct mystruct **mydata; 
mi_query(miQ_FUNC_USERPTR, state, 0, &mydata) ; 
*mydata = mi_mem_allocate(...); 
(*mydata)->cos_angle = cos(*mi_eval_scalar(&paras->angle) ) ; 


t 
} 
DLLEXPORT void myshader_exit ( /* exit shader */ 
misState *state, 
struct myshader *paras) 
3 
if (paras) { 
struct mystruct **mydata; 
mi_query(miQ_FUNC_USERPTR, state, 0, &mydata) ; 
mi_mem_release(*mydata) ; 
t 
return (miTRUE) ; 
} 
DLLEXPORT void myshader ( /* main shader */ 
miState *state, 
struct myshader *paras) 
{ 
struct mystruct **mydata; 
mi_query(miQ_FUNC_USERPTR, state, 0, &mydata) ; 
...use (*mydata)->cos_angle... 
return (miTRUE) ; 
} 


Note that the init shader first requests instance initializations by setting zmst_req to miTRUE, and 
creating the instance data for each instance initialization, indicated by a nonzero paras pointer. 
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(Refer to page 403 for information on the difference between shader initialization and shader 
instance initialization.) Similarly, the exit instance shader deletes the data. 


Note that this relies on the angle shader parameter to be constant. It is obtained only once with 
mi_eval_scalar, so this parameter cannot be attached to another shader that computes a new angle 
for each shader call. Since this is often desirable, the example above is a bit contrived. 


3.28.3. Thread-Local Storage? 


Sometimes shaders need to share data, but need to modify it. Sharing would allow using the first 
method for constant data, but that does not permit changing the data during rendering because 
no consistent writes are possible — multiple instances of the shaders in different threads may write 
to the same data simultaneously. This can corrupt even simple operations such as incrementing a 
variable, because the execution order is unpredictable. The sequence read, write, readg write 
in threads A and B works, but there is no way to avoid the sequence read, readg write, writes. 
This problem is called a race condition, and it can cause one increment to be lost, in rare and 
hard-to-debug cases. Locking would prevent that but may cause an unacceptable performance 
loss. 


mental ray 2.1 allows solving this problem by allocating an array with one member per thread in 
the init shader. The number of threads could be obtained by calling mi_par_nthreads, and it was 
guaranteed that no thread with a thread number state — thread outside that range would ever 
call a shader. However, mental ray 3.x no longer makes this guarantee; the number of threads may 
change at any time so mi_par_nthreads is deprecated. It is still available but always returns 65, 
which may allow unported shaders to limp along on hosts with few (say, up to 16) CPUs. This 
means that shaders have to implement a hashing scheme to use the array method in mental ray 
3.x. To simplify this, mental ray 3.1 introduces a standard mechanism for thread-local storage. 


Thread-local storage avoids the race condition by providing one copy of the data to each thread. 
Multiple threads can execute simultaneously but with any single thread the execution is strictly 
sequential, so that the read/write race condition cannot happen. Here is an example that counts 
shader calls: 


DLLEXPORT void myshader ( /* main shader */ 
miState *State, 
struct myshader *paras, 
miBoolean *inst_req) 
{ 
int *counter; 


mi_query(miQ_FUNC_TLS_GET, state, miNULLTAG, &counter) ; 

if ('counter) { 
counter = mi_mem_allocate(sizeof (int) ); 
mi_query(miQ_FUNC_TLS_SET, state, miNULLTAG, &counter) ; 
*counter = OQ; 

br 


(*counter) ++; 
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return (miTRUE) ; 


DLLEXPORT miBoolean myshader_init ( 
miState *state, 
struct myshader *paras, 
miBoolean *init_req) 


*init_req = miTRUE; 
return (miTRUE) ; 
} 


DLLEXPORT void myshader_exit ( /* exit shader */ 
miState *state, 
struct myshader *paras) 


int *kDtIS ; 
int num, i, total = 0; 


if (!paras) 

return (miTRUE) ; 
mi_query(miQ_FUNC_TLS_GETALL, state, miNULLTAG, &counters, &num) ; 
for (i=0; i < num; i++) { 

total += *counters [i]; 

mi_mem_release(counters [il] ) ; 


t 


mi_info("myshader was called %d times", total); 
return (miTRUE) ; 


The thread-local data is a single integer that counts shader calls in this thread. Since init shaders 
are called once per shader or once per shader instance, but not once every time the shader is called 
in a new thread, the data cannot be installed and initialized in the init shader. Instead, it is created 
in the main body if it did not already exist. This is safe because no two threads will get the same 
pointer returned by miQ_FUNC_TLS_GET. (Note that setting *counter to zero is actually redundant 
because mi_mem_allocate always returns zeroed memory.) 


The example exit shader collects all the thread-local counters of all threads that installed a counter, 
and computes and prints the total. It is done during shader instance exit, not the shader exit, by 
checking that paras is nonzero. This requires shader instance init/exit to be enabled in the init 
function by setting init_req to miTRUE. 


This will only work on a single host because each host exits its own shaders, and there is no way 
to communicate the counters between hosts. Moreover, slave hosts may come and go*', and may 


call their exit shaders multiple times for a single frame. 


Thread-local shader storage relies on three new mi_query modes: 


e miQ_FUNC_TLS_SET*"! saves a user pointer passed as fourth argument. Different threads will 
store the pointers separately and will not interfere with each other. Note that this mode 
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differs from all other mz_query modes in that it stores data instead of retrieving data. 


e miQ_FUNC_TLS_GET°' retrieves the previously set pointer into the address given by the 
fourth argument, or a null pointer if no pointer has been set (which normally prompts the 
caller to set the pointer now). 


e miQ_FUNC_TLS_GETALL*" retrieves the address of an array of all the pointers stored using 
miQ_FUNC_TLS_SET, one per thread that did so. The size of the table is stored in the address 
provided as the fifth argument and should point to an integer variable. Threads that did not 
set a pointer are not represented in the array. This mode should be used in the exit shader 
to release all allocated thread-local data. 


The second argument to mi_query must be the shader state, and the third must be a null tag. A 
mi_query call with these modes in mental ray 2.1 and 3.0 will return miFALSE. 


3.29 Automatic Source Generation with mkmishader 


In order to write a new shader, a number of prototypes and other mechanical work must be done, 
such as writing prototypes, evaluation of parameters, versioning, and so on. The mkmishader 
utility can do this automatically. For example, the mib1llum_lambert shader in the base shader 
library has the following .mi declaration: | 


declare shader 
color "mib_illum_lambert" ( 


color "ambience", 
color "ambient", 
color "diffuse", 
integer "mode", 
array light "lights" 


) 
version 2 
end declare 


If this declaration is stored in a file, and the mkmishader utility is run with the -i option (which 
creates init and exit shaders), a new file mib_illum_lambert.c is created with the following 
content: 


#include <stdio.h> 
#include <math.h> 
#include <shader.h> 


typedef struct { 


miColor ambience; 
miColor ambient ; 
miColor diffuse; 


milInteger mode ; 
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int i_lights; 
int n_lights; 
miTag lights[1]; 


} mib_illum_lambert_t; 


DLLEXPORT int mib_illum_lambert_version(void) {return(2) ;} 


DLLEXPORT miBoolean mib_illum_lambert_init ( 


misState *State, 
mib_illum_lambert_t *param, 
miBoolean *init_req) 
1. 
if (!param) { 
/* shader init */ 
*xinit_req = miTRUE; /* do instance inits */ 
} else { 
/* shader instance init */ 
} 
return (miTRUE) ; 
} 


DLLEXPORT miBoolean mib_illum_lambert_exit( 
miState *state, 
mib_illum_lambert_t *param) 


{ 
if (param) { 
/* shader instance exit */ 
+ else { 
/* shader exit */ 
r 
return (miTRUE) ; 
} 
DLLEXPORT miBoolean mib_illum_lambert ( 
miColor *result, 
miState *state, 


mib_illum_lambert_t *param) 


* get parameter values. It is inefficient to do this all 
* at the beginning of the code. Move the assignments here 
* to where the values are first used. You may want to use 


* pointers for colors and vectors. 


* / 


miColor ambience = *mi_eval_color(&param->ambience) ; 

miColor ambient = *mi_eval_color(&param->ambient) ; 

miColor diffuse = *mi_eval_color(&param->diffuse) ; 

miInteger mode = *mi_eval_integer (&param->mode) ; 

int i_lights = *mi_eval_integer(&param->i_lights) ; 

int n_lights = *mi_eval_integer(&param->n_lights) ; 

struct lights_s *lights = (struct lights_s *)mi_eval( 
state, param->lights) ; 


/* 
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* sample array loops 
od 
int 13 
for (i=0; i < n_lights; i++) { 
/* use lights[i_lights + i]; */ 
t 


/* 
* set shader results. ‘‘+=’’ etc. is useful for shaders 
* in shader lists but other shaders may need to simply 
* assign result variables. 


* / 


result->r += 0.0; 
result->g += 0.0; 
result->b += 0.0; 
result->a += 0.0; 
return (miTRUE) ; 
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This skeleton source code can then be filled in with the implementation of the actual algorithm. 
It is important to move the mz_eval functions to the places where they are first used because if 
the shader does not need a variable it is faster to not access it. For example, if the light array 
lights is empty, so n_lights is zero, then there is no need to access 1_light, lights, and diffuse. If 
those parameters are assigned to other shaders that would have to be called on access, not calling 
mi_eval is a significant performance improvement. The functions used in this skeleton will be 
described later. 


3.30 Shaders and Trace Functions 


Trace functions are functions provided by mental ray that allow a shader to cast a ray into the 
scene, most of them using standard ray tracing. Not all types of tracing functions can be used 
in all types of shaders. Conversely, many trace functions cause shaders to be called. This section 
lists these interdependencies. 


The following table shows which shaders are called from which trace functions. o means no, 
e means yes. Displacement, contour, and photon shaders are never called by any of the functions, 
and may not call any of them. 
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function calls shader lens mtl env light shad vol 


mi_trace_eye 
mi_trace_reflection 
mi_trace_refraction 
m1i_trace_transparent 


mi_trace_environment 
mi_trace_light 
mi_sample_light 
mi_trace_shadow 
mi_trace_shadow_seg 


Oo 0 0 © ©@ OO 8.8 
Oo Oo 0 0 0 8 @ @ 
oO oO 0 OC @®@ @©@ @ @ @ 
Oo O ® ® 0 0 0 0 90 
® @® oOo 00 0 0 0 0 
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Environment rays do not have entries in this tree. The data in the tree is used for acceleration and 
can be overridden if a shader wants to cast rays not normally allowed, by setting the state variable 
state—cache to zero. This should only be done when necessary because it reduces efficiency. The 
following table shows which trace functions may be called from which shaders: 


ray _ light 
shader calls function lens mtl env light shad vol vol 
O 


mi_trace_eye 
mi_trace_reflection 
mi_trace_refraction 


O 


mi_trace_transparent 
mi_trace_environment 
mi_trace_light 
mi_sample_light 
mi_trace shadow 
mi_trace shadow_seg 
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e yes 


x yes, if the shader generates an artificial intersection point by setting point, normal, and 
normal_geom in the state. 


xx yes, if the shader removes RC’s internal ray tree data by setting cache in the state to NULL 
and generates an artificial intersection point if none is present. 


3.31 Example Scene with Custom Shader 


This section shows how to create a .mi file that uses a custom shader that is linked at runtime. 
This example uses a texture shader, but the same procedure is used to create and link any other 


type of shader. 
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Step 1: Writing the Shader Source 


This texture shader operates in object space and colors the object into eight cubes that meet 
at the object coordinate origin. A cube mapped with this texture looks like a Rubik’s cube for 
beginners that consists of eight subcubes, each with a different color. The brightness of the colors 
is determined by the shader parameters min and max. 


#include <stdio.h> 
#include "shader.h" 


struct mytexture { miScalar min, max; }; 
int mytexture_version(void) {return(1) ;} 


miBoolean mytexture( 


miColor *result, 
miState *State, 
struct mytexture *paras) 

{ 
miVector vec; 
miScalar min, max; 
mi_point_to_object(state, &vec, &state->point) ; 
min = *mi_eval_scalar(&paras->min) ; 
max = *mi_eval_scalar(&paras->max) ; 
result->r = vec.x < O ? min : max; 
result->g = vec.y < O ? min : max; 
result->b = vec.z < O ? min : max; 
result->a = 1; 
return (miTRUE) ; 

} 


This code should be written to a file mytexture.c. 
Step 2: Compiling and Linking 


There are several ways to integrate this shader into a scene file: placing the source code directly 
into the .mi file with $code and $end code statements, referencing the source file with a code 
statement, or compiling the source and referencing the object code with a link statement. The 
recommended method, and also the fastest method, is to create a DSO (Dynamic Shared Object) 
file on Unix systems, ora DLL on Windows NT systems. To do this, the shader must be compiled 
and linked manually: 


% cc -02 -shared -o mytexture.so mytexture.c 


This example uses SGI syntax; other compilers require different command lines. See page 187 
for the commands required for different types of systems. You may also want to specify the 
-g option for debugging, -02 for optimization, or -Idirectory to tell the compiler where the 
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directory containing the shader.h file can be found (refer to the compiler documentation for 
details). After this command, there is a mytexture.so DSO in the current directory; move it to a 
place accessible to all hosts, for example with 


% mv mytexture.so /usr/share/local 


Assuming a directory /usy/share/local exists and is accessible to you. You may also choose a 
directory such as /usr/tmp, but since this directory is not normally accessible from other hosts 
that you want to use as slaves (at least not under this name), you will have to copy mytexture.so 
to /usr/tmp on the other hosts too. 


Step 3: Linking and Declaring the Shader 


Now the shader needs to be linked and declared in the .mi scene file that contains the object 
or objects to be mapped with the new texture. Linking means that the DSO (or DLL) becomes 
callable by mental ray, and the declaration informs mental ray about the shader parameters: 


link "/usr/share/local/mytexture.so" 

declare shader 
color "mytexture" (scalar "min", scalar "max") 
version 1 

end declare 


It is important that the declaration matches the type and order of the C declaration in the source 
file, struct mytexture. These lines should be added near the beginning of the .mi file, before the first 
use and before the frame statement if there is one. For complicated DSOs, it is recommended to 
put all declarations for the library into a separate file mytexture.mi, and use a $include statement: 


link "/usr/share/local/mytexture.so" 
$include "/usr/share/local/mytexture.mi" 


Either way, the library must be linked before the declaration is given because mental ray makes 
sure that a declared shader exists. 


Step 4: Using the Shader 


Now the shader can be used in a real .mi file. The following example puts the texture on a cube. 
Note that the cube is defined in object space, with the origin at the center of the cube; this is the 
space that the mytexture shader picks up with mi_point-_to_object. 


verbose on 
$include <base.mi> 
link "base.so" 
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link "/usr/share/local/mytexture.so" 


declare shader 


color "mytexture" (scalar "min", scalar "max" 


version 1 
end declare 


options "opt" 
samples 
contrast 
jitter 
object space 
end options 


camera "cam" 
frame 
output 
focal 
aperture 
aspect 
resolution 

end camera 


instance "cam_inst" 
transform 


end instance 


light "light" 


-2 0 

Oct 0,1. O22 

0 

i. 

"rgb" "zirgb" 

50 

44 

1.18 

500 424 

"cam" 

0.7719 0.3042 -0.5582 0.0 
0.0000 0.8781 0.4785 0.0 
0.6357 -0.3693 0.6778 0.0 
0.0000 0.0000 -2.5000 1.0 


"mib_light_point" ( 


"color" 
) 
origin 
end light 


1 iy Oe | 


000 


instance "light_inst" "light" 


transform 


end instance 


color texture "tex" 
"mytexture" ( 
rs ol 
"max " 


1 0 0 0 
0.1. 0 2 
0 0 1 90 
“2-3-2 
0.3; 
1.0 


material "mtl" opaque 
"mib_illum_phong" ( 


"ambience" 


cS aed wid 
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"ambient" = "tex", 

"diffuse" = "tex", 

“specular” 111, 

"exponent" 50, 

"lights" [ “light_inst" |] 
) 


end material 


object "cube" 


visible 
tag 1 
group 
-0.5 -Gas. -0.5 
“0.5 -0,57_ 0.5 
“0.5 Ob oS 
“0.5 Q0.5 01% 
0,5 ~0.5° siee 
0.5 “0.5 Gas 
O.8- 0.8 “O65 
0.6 0.5 0.5 
v O v i ¥ 2 v3 
v4 7 5 v 6 v 7 
p “atl” 0 2 2 2 
P 1&6 7 3B 
p 5 4 6 7 
p 4 0 2 6 
Pp 41.6; cP 
p 2 & f S&S 
end group 
end object 
instance "cube_inst" "cube" 
transform 1 &@ DO Q 
G i. | 
Oo Oo 1° 9 
oo Od 


end instance 
instgroup "rootgrp" 
"cam_inst" "“light_inst" "cube_inst" 


end instgroup 


render "rootgrp" "cam_inst" "opt" 


The following image shows the result of rendering this scene with the command line ray 
example .mi (assuming that the above scene example was written to a file example .mi): 
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3.32 Accelerated Graphics Hardware Shaders: 


mental ray 3.3 and later support rendering with graphics hardware. To achieve the same results 
with hardware and software (within the capabilities of the graphics hardware), it is necessary to 
provide a hardware shader equivalent for each software shader used in the scene. 


mental ray will automatically convert graphs of software shaders, and Phenomena in particular, 
by compiling the existing hardware shader nodes into a program stream accepted by the graphics 
hardware. This requires that the hardware shaders are written in a language like NVIDIA’s Cg 
1.2 language that supports the necessary interface definitions. 


Shaders written in other languages are accepted as well, but cannot be used as nodes in shader 
graphs. In these cases it is necessary to write a hardware shader that represents the entire graph 
or Phenomenon. 


For general information on hardware rendering in mental ray 3.3, see page 52, and the bibliography 
at the end of this manual. This section describes how to write hardware shaders. 
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3.32.1 Shader Interfaces 


To realize the goal of providing inaccurate but fast previews, it is important to replace any software 
node with a hardware node, or omit it altogether, and still obtain a reasonable simplified image. 
Global illumination has no hardware equivalent, but a software shader that renders an object layer 
(such as the three object nodes in the above graphs) may have an equivalent or simplified hardware 
version. This requires that a shader interface is introduced that allows defining hardware and 
software shaders that provide a similar interface to the scene. The following intrinsic differences 
need to be abstracted: 


e Software shaders have inputs and outputs. It is possible to create graphs of shaders where 
shaders obtain their inputs from the outputs of other shaders. Such graphs can be used to 
create Phenomena, which encapsulate one or more shader graphs and other information 
such that the Phenomenon appears like a monolithic shader. This allows a separation of 
functions: different components of a complex effect may be built from simple shaders, each 
taking care of some aspect of the effect. 


e Hardware shaders consist of two functions, one modifying geometry and precalculating 
data (called the vertex shader), and one doing the actual shading calculation (the fragment 
shader). There is also a constant shared data storage called uniform variables. Both types of 
shaders are monolithic; it is not possible to build up complex effects from simple dedicated 
functions. Also, the uniform variables are the only place to pass input parameters to both 
types of shaders. Most importantly, mental ray’s separation of surface, volume, texture, and 
light shaders cannot be represented in hardware. 


However, NVIDIA’s Cg 1.2 shader language compiler has the ability to compile the shader 
nodes of Phenomena and their connections into monolithic hardware shaders. This was 
developed in close cooperation between NVIDIA and mental images. 


Although the implementation is obviously different, both software shaders and hardware shaders 
accept parameters in a similar way. mental ray supports mapping standard mental ray shader 
parameters to uniform variables, unpacking information into a form that the hardware shaders 
can use: 


e Simple data formats such as vectors, floats, and matrices can be stored in uniform variables 
without change. 


e Integers and booleans require conversion to floating-point format. 


e Lights require obtaining light information from the referenced light instances and light 
elements, such as position, orientation, cone angles, and energy, storing the resulting data 
set in uniform variables. Lights must be part of the material definition otherwise they will 
no be part of the illumination calculation in the fragment shader. 


e Textures and other maps require preloading the necessary textures into hardware memory, 
probably at a reduced resolution to fit into the limited space. The necessary reference data 
is stored in uniform variables. 
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Software shaders have no inherent limit on the number of lights and textures. Hardware shaders 
do, because the number of uniform variables, registers or number of instructions are rather 
limited. Effects that would exceed this limit require layering. For example, if there is only room 
for ten lights in the uniform variables but the shader’s light list contains twenty, the shader must 
be called twice to layer the effect. The design does not attempt to automate this at this time 
because it is not known how lights and other parameters interact. If the shader fails to load, it 
will either render with a default hardware material or with rendered the software version. 


3.32.2 Shader Declarations 


Software and hardware shaders are both declared. A software shader declaration is little more 
than a list of the parameters accepted by the shader and their data types, without the actual values 
(they are defined later when the shader is used). Such a declaration might look like this, using 
mental ray’s .mi scene definition syntax: 


declare shader 
color "mib_illum_lambert" ( 


color "ambience", 
color "ambient", 
color "diffuse", 
integer "mode", 
array light "lights" 


) 
version 2 
end declare 


The declaration is the same for hardware and software shaders. This makes it simple to substitute 
a hardware shader for a software shader if both are written with the same interface parameters. 
Hardware shaders use the declaration to tell mental ray how the input parameters should be 
stored in uniform variables, just like software shaders use this information for building a stack 
frame for the C/C++ shader code. 


The idea is that the declaration is the gateway between the shader and the hardware. Such a 
declaration may be fairly complex, but once written by the shader writer, the shader looks very 
similar to any other shader. The burden of writing the shader and declaring it is shifted to the 
programmer in a way that the artist, who later uses the shader, does not have to care about the 
complexities of hardware shader writing at all. 


The only exception is that shaders might have built-in limitations not usually found in software 
shaders, such as accepting only a limited number of lights or textures; but these limitations are 
all in the domain of scene design and not in the domain of programming. Since the artist and 
the programmer require different skill sets, and are not normally the same person, mental ray 
maintains a strict separation of these two roles. 


Hardware shaders come with additional information that is hidden behind the parameter 
declaration, in ways that only the programmer but not the artist needs to understand. A hardware 
shader declaration needs to contain the following information: 
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The implementation of the vertex shader, if required. 


The implementation of the fragment shader. 


An optional C/C++ function that can perform extra OpenGL setup and shutdown. (Most 
hardware shaders do not need this.) 


Hardware requirements, such as the availability of a certain OpenGL version of a feature. 
The following section describes an example based on NVIDIA’s Cg language. 


3.32.3. Shader Implementation 


After the declaration is known, the shader must be implemented. This example uses NVIDIA’s 
Cg language, version 1.2. Only a rough outline of a Phong shading material is given, the light 
shaders are omitted to keep this short. 


The hardware performs shading in two stages: the vertex shader is run per vertex, and the fragment 
shader is run per shaded point on the triangle defined by three vertices that have passed through 
the vertex shader. Here is an overview over the data flow in the example: 


uniforms 


mental ray app2vert 


vert2frag pixels 


vertex shader fragment shader frame buffer 


mental ray installs the shaders on the graphics board, and provides two sets of information to 
them: app2vert is a structure that contains information about the current vertex. It is basically 
equivalent to the miState structure passed to software shaders. mental ray passes it in standard 
hardware registers, such as POSITION, that are defined by the hardware. (By convention, NVIDIA 
uses all-capitals names for these registers.) In Cg syntax, this structure is defined as 


struct app2vert 


{ 
float4 position : POSITION; 
float3 normal : NORMAL; 
float2 texCoord0 : TEXCOORDO; 
float2 texCoordi : TEACOGRD1's 


float3 derivU ; ALIS 
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float3 derivV . DI iae 


r 


The colon notation describes how the fields (left) are mapped to the hardware registers (right). 
The vertex shader performs some computations and creates a new structure called vert2frag. Since 
rendering is done per triangle, a fragment shader, which is called for every pixel in that triangle, 
receives an interpolated vert2frag structure every time it is called for a point in the triangle. In 
this example, the fields of that structure are declared in Cg as: 


struct vert2frag 


4 
float4 hPosition : POSITION; 
float2 texCoord0 : TEXCOORDO; 
float2 texCoordi : TEXCOORD1; 
float3 cPosition : TEXCOORD2; // camera-space position 
float3 cNormal : TEXCOORDS ; // camera-space normal 
float3 position : TEXCOORD4; // object-space position 
float3 normal : TEXCOORDS ; // object-space normal 
float3 derivU : TEXCOORD6; // U derivative 
float3 derivV : TEXCOORD7 ; // V derivative 
float3 screen : WPOS; // screen-space position 
}; 


This structure contains the projected position, texture coordinates, normals, and derivatives. 
Again, the named parameters are mapped to a fixed set of all-uppercase hardware registers, such 
as TEXCOORDO. 


Finally, shaders also receive shader parameters. The set of parameters must be declared to mental 
ray in a shader declaration. Unlike the previous two structure definitions, which are read by the 
Cg compiler, the parameter declaration uses .mi syntax and is read by mental ray: 


declare shader 
color "mib_phong_specular" ( 


color "ambience", 
color "ambient", 
color "diffuse", 
color "specular", 
scalar "exponent", 
array light "lights", 


) 


end declare 


This declaration is for the shader named mi_phong_specular, which has six parameters. The name 
will be used by mental ray to locate the Cg shader to load (this will be explained in more detail 
later). There is no equivalent Cg declaration for the parameter list; instead, Cg expects parameters 
to be declared with the keyword uniform embedded in the Cg function implementation. 


3 


3.32 Accelerated Graphics Hardware Shaders?’ 423 


Here is the implementation of the example main vertex shader. The same vertex shader can often 
be combined with many different fragment shaders to implement a variety of effects, so it is 
stored in a separate file: 


vert2frag main( 


app2vert IN, 
uniform cgglMatrix mx) 


vert2frag OUT; 


#ifdef PROFILE_ARBVP1 


#endif 


ModelViewProj = glstate.matrix.mvp; 
ModelView = glstate.matrix.modelview[0] ; 
ModelViewIT = glstate.matrix.invtrans.modelview[0] ; 


// copy the object space information 
OUT.position = IN.position.xyz; 
OUT.normal = IN.normal.xyz; 


// set the homogeneous camera-space position of the vertex 
// and compute the camera-space position for lighting 
OUT.hPosition = mul(mx.ModelViewProj, IN.position) ; 
OUT.cPosition = mul(mx.ModelView, IN.position) .xyz; 


// make derivative vector in camera space 
float3x3 rot = (float3x3)mx.ModelView; 
OUT .derivU = mul(rot, IN.derivU) .xyz; 
OUT.derivV mul(rot, IN.derivV) .xyz; 


// transform normal from model space to camera space 
OUT.cNormal = normalize (mul ((float3x3)mx.ModelViewIT, IN.normal.xyz)) ; 


// transfer the texture 
OUT.texCoordO = IN.texCoord0; 
OUT.texCoordi = IN.texCoord1; 


return QUT; 


Each shader is stored in a separate Cg file, and the shader mainline must be named main. Note 
that the shader is declared to return a vert2frag structure, which is the data later passed to the 
fragment shader after interpolation. 


This is the corresponding fragment shader: 


struct mib_illum_phong : miiColor 


{ 


// shader parameter definition, must agree with .mi declaration 
miiColor ambience, ambient, diffuse, specular; 
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miiScalar exponent ; 
miiLight lights []; 


float4 eval(vert2frag p) { 

float4 result; 

float4 lambience = ambience.eval(p) ; 
float4 lambient = ambient.eval(p); 

float4 ldiffuse = diffuse.eval(p); 

float4 lspecular = specular.eval(p) ; 

float lexponent = exponent.eval(p) ; 
float3 vdir = normalize(p.cPosition) ; 


result = lambience * lambient; 


// Material calculation for each light 
for (int i=0; i < lights.length; i++) { 
misLightOut light = lights[i].eval(p); 


// Lambert’s cosine law 
result += light.dot_nl * ldiffuse * light.color; 


// Phong’s cosine power 

float s = mi_phong_specular(lexponent, light.dir, 
-vdir, p.cNormal) ; 

result += s * lspecular * light.color; 


} 


return result; 


r 


To keep this example simple, the light shaders have been omitted, and the Cg code of the light_illum 
and mi_phong-_specular functions is not shown. Note the uniform arguments of this function: 
they correspond exactly to the .mi declaration shown above, with thew mz prefix replacing the mi 
prefix. Since NVIDIA hardware registers store floating-point values, the integer mode is stored 
as a floating-point number. Also note that the shader returns a color, indicated by the miiColor 
return type after the colon. 


The Cg 1.2 language simplifies inter-shader communication greatly, which is important for 
automatic translation of mental ray’s Phenomena to Cg shader graphs. The need to explicitly 
reference sub-shaders for multiple light sources or texture generation is handled automatically. 
The key function is the eval member function, which plays the same role as the mi_eval functions 
in mental ray software shaders. 


Shader writing for other hardware boards, such as ATI boards, is very similar. The Cg 1.2 
compiler can be used with its ARB profile, which generates code that conforms to the OpenGL 
Architecture Review Board (ARB) baseline definition. (NVIDIA’s Cg compiler is not expected 
to cater to ATT’s special extensions.) However, all the components are the same. The forthcoming 
OpenGL 2 standard will define a shader language equivalent to Cg to avoid having to use the 
less intuitive assembly language. At this time (March 2004), this new language does not accept 
interface constructs required for mental ray Phenomena. 
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3.32.4 Portability 


Portability refers to the ability to render a scene, including all its hardware shaders, on a wide 
range of graphics hardware. This is not easy since graphics hardware from two different vendors, 
or even successive hardware generations from the same vendor, can vary drastically. This can be 
easily solved by either supporting a common subset of all hardware variants, or by requiring a 
different shader implementation for each variant. Neither is desirable, although it must remain 
possible to tailor a shader for a specific hardware or application. 


mental ray is designed to separate hardware-dependencies from scene modeling as much as 


possible. 


There are six architecture levels: 


The shader level is the domain of artists who design the scene. Like with all shaders, the 
artist needs to be aware of their functionality and limitations, but there is no need to be 
aware of the underlying hardware. In fact, many of these shaders have both a hardware and 
a software version. 


The shader declaration (and implementation) are performed by a programmer who designs 
new shaders. As described above, shader declarations differ between hardware and software 
shaders. Some declarations are provided by mental images; others may be written by 
customers. This requires programming skills. 


The hardware declaration describes a specific graphics hardware. There are different 
declarations for various NVIDIA, ATI, and other boards. In principle, new hardware 
requires only changing the hardware description, although additional hardware capabilities 
might make possible more sophisticated shaders. 


The mental ray infrastructure is provided by mental images. It is hardware-agnostic as much 
as possible, and mainly concerned with interpreting declarations and mapping rendering 
requests to OpenGL calls. 
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e The graphics hardware is the physical graphics board plugged into the computer. 


The hardware declaration describes the capabilities of the installed board. Much of this can be 
read directly from the board; OpenGL provides various information about which features are 
supported by the board, and hardware limits such as the size of shaders, size of texture memory, 
or the number of uniform variables. Some items remain under user control through the hardware 
declaration, such as symbolic register mappings and directories to search for shader declaration 


files. 


3.32.5 Loading Hardware Shaders 


mental ray 3.3 uses OpenGL not only for defining a scene, but also to load hardware shaders. 
Hardware shaders include the vertex and fragment shader, precompiled uniform variables, and 
additional parameters. Just as mental ray relies on external shared libraries (DSO)s containing 
precompiled C/C++ software shaders, it relies on external libraries containing hardware shaders. 
The libraries are created by external compilers such as NVIDIA’s Cg compiler from source code 
provided by the shader writer: 


required during shader development required for rendering 


| | 


a ae 
Editor C C compiler mental ray 
se 
Editor Cg 
source 


Cg compiler 
OpenGL 
graphics hardware 
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The hardware shader pipeline mirrors mental ray’s existing software pipeline, except that the end 
result is not a DSO executed within mental ray, but a Cg hardware shader library. Hardware 
shaders are collected, processed, compiled, and sent to OpenGL for installation on the graphics 
hardware where they are executed. 


NVIDIA’s Cg compiler is only one example of a shader compiler. It accepts a high-level source 
code format that is designed to look like C code, with various restrictions and extensions. It 
is primarily targeted at graphics hardware designed by NVIDIA, but can also generate code 
for other graphics architectures such as OpenGL ARB through the use of profiles. All graphics 
vendors accept shader source code written in a form of specialized low-level assembly language, 
all specific to the vendor’s graphics hardware; in this case the Cg or other compiler is not required. 
The upcoming OpenGL 2.0 standard will accept shaders in a format common to all vendors, but 
at this time (March 2004) hardware shader libraries must be designed and compiled separately 
for each hardware vendor. 


Since the hardware shader source code and libraries currently differ greatly from vendor to 
vendor, and from hardware generation to hardware generation, mental ray does not attempt 
to integrate a compiler. If it did, it would become subject to the rapid change in the hardware 
industry, and would have to be modified each time any graphics hardware vendor designed a new 
board or language feature. It is important to keep mental ray hardware-agnostic and compatible 
with all graphics hardware from any vendor. 


3.32.6 Extracting Cg Shader Code 


mental ray will use the Cg compiler to build hardware shaders from shader graphs in Phenomena. 
This involves collecting and preparing the Cg code that implements the subshaders that form the 
Phenomenon, passing this to NVIDIA’s Cg compiler, and sending the resulting assembly code 
to the graphics board. This process is normally invisible and automatic. 


However, it is sometimes useful to extract the Cg compiler input and output for debugging 
purposes, or to transplant the shader into a game platform. This allows mental ray to be used as 
a prototyping system for shader development with the full benefit of Phenomenon construction; 
and then extracting the resulting hardware shaders for use in a game engine. This is done with 
the command-line options 


-hardware_echo "path" -- 
-hardware_echo error "path" -- 


The first variant saves all shaders into the directory path; the second saves only those shaders 
for which the Cg compiler has reported an error. The latter mode is intended for debugging by 
shader authors. Saving a shader means creating four files per material that uses a Cg hardware 


shader: 


e materialname.cg contains the Cg input to the compiler. 


e materialname.asm contains the assembly output of the Cg compiler. 
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e materialname.C contains sample C++ code that installs the shader with the appropriate 
OpenGL calls. 


e materialname.txt contains informational messages about the construction of the shader 
graph with all its connections. 


Note that the file names are constructed from the name of the material containing the hardware 
shaders, not from the name of a shader, because many shaders are usually collected to build a Cg 
input file, and because two materials using the same shader with different parameters will result 


in different Cg files. 


3.33. Hardware Shader Implementation 


Hardware shader names can be explicitly specified in materials, or automatically constructed 
from software shader names by adding a vendor prefix like migl_. Once the shader name is 
known, mental ray will perform two operations: 


e First, mental ray will attempt to call a software function whose name is constructed by 
adding the prefix to the shader name. For example, if the hardware shader name is myphong 
and the hardware shader is implemented in Cg, mental ray will try to call the software 
function micg_myphong. This is not a hardware or software shader but a C/C++ function 
that can be used to do special setup operations needed for the shader, such as copying data 
to the graphics board or calling special GL functions needed by the shader. This function 
is optional and rarely necessary. 


This function is normally implemented in the shader support library. For example, the 
software shader library base.so might have a support library migl_base.so for Cg 
hardware shaders. 


e Second, the actual shader is loaded from files on disk into the graphics board. Files are 
searched for with the hardware search path configured with the MI_REG_HARDWARE registry 
key in the startup file, or the -hardware_path command-line option. The file name must 
exactly match the shader name, plus a postfix: 


postfix contents 
_v.cg NVIDIA Cg vertex shaders 
£.cg NVIDIA Cg fragment shaders 


Either one may be missing if the shader does not require this type of shader. (Most shaders 
do not require a vertex shader and provide only a fragment shader.) For example, for 
NVIDIA hardware, if the hardware shader name is myphong, mental ray will load the Cg 
files myphong_v.cg and myphong-f .cg. 


e If no such Cg shader can be found, or -hardware native or -hardware fast is specified 
on the command line to turn off all programmable shaders, mental ray will use plain 
hardwired OpenGL shading. This requires a C/C++ function that performs the necessary 
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OpenGL calls to load colors etc. This function follows the same conventions as the support 
functions in the first item: the shaders get the prefix mig/_, for example migl_myphong, and 
they are loaded from the library migl_base.so. The only difference is that they are loaded 
instead of, rather than in addition to, any hardware shaders. 


3.33.1 Writing Hardware Shaders 


Hardware shaders are closely tied to the graphics hardware available. It is generally not possible 
to use a Cg shader that uses special NVIDIA hardware features for ATI hardware, and vice versa. 
The main classes are: 


e NVIDIA shaders are written in NVIDIA’s Cg 1.2 language, which is loosely based on C. It 
supports shader graphs and is well-suited for mental ray’s shader graphs and Phenomena. 
NVIDIA hardware shaders come in pairs: a vertex shader operates on triangle vertices, and 
a fragment shader operates on pixel colors. Most of the time, only a fragment shader is 
supplied; non-default vertex shader are rarely needed. 


e OpenGL prior to version 2.0 does not support programmable shaders at all. All functions 
must be mapped to the hardwired shading model. Only very simple shaders can be mapped 
to OpenGL hardware, but it is still useful for very fast low-quality previews. 


e OpenGL 2.0 supports a native shading language similar to NVIDIA’s Cg, but it has not 
been finalized at this time and will not be described here. 


e HLSL support may be added in future versions of mental ray that support DirectX. HLSL 
is the native shader language of DirectX, which is Microsoft’s proprietary alternative to 
OpenGL It and may become available for special OEM versions of mental ray. Unlike 
NVIDIA’s Cg, HLSL is not portable. 


The main difference between software and hardware shaders to keep in mind is that hardware 
shading always proceeds triangle by triangle, not ray by ray. Each of the three vertices of the 
triangle pass through a vertex shader which may move vertices, alter normals, or set up other 
information tied to the vertex. 


When all three vertices have been set up, the hardware rasterizes the triangle by picking points 
on the triangle that correspond to image pixels. For each of them, the vertex information stored 
by the vertex shader is interpolated, and the fragment shader is called to compute a pixel color 
value that is then stored or merged into the frame buffer. 


For the shader writer, this means that there is no geometrical information except as stored by 
the vertex shader. There is no way to, for example, trace a ray, find a ray or volume length, or 
do other operations that involve other geometry. Reflections, shadows, and other features are 
available only through precomputed map images such as texture maps. 


mental ray supports a large number of shader types. Only material and light shaders are directly 
supported. Since Cg supports shader graphs, subshaders including texture shaders are supported 
as well. 
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shader type 


material 
light 
subshaders 
texture 
volume 
environment 
lens 

output 


shadow 


photon 


geometry 


displacement 


supported 
supported 
supported in Cg 1.2 
supported 

not supported 


supported for cameras but not materials 


not supported; will never support ray bending 


not supported 


not applicable; shadow shaders are called during ray tracing only. Hardware 
rendering uses shadow maps instead. 


not applicable; photon mapping is based on ray tracing and must be 
completed betore hardware rendering begins. 


not applicable, geometry is built before rendering begins. 


not applicable for the same reason, although vertex shaders can be written 
that displace preexisting vertices. 


The next sections will show how to write a simple Phong shader and a point light shader. 


3.33.2. Phenomena 


Phenomena are effects implemented as one or more cooperating shader graphs and instructions 
for integrating the Phenomenon into a scene. Phenomena can be used like shaders, but they have 
access to the scene graph and may consist of a large number of subshaders. 


If all subshaders in a shader graph have Cg implementations, mental ray can collect the entire 
graph and all its internal connections, Phenomenon interface assignments, and constants and pass 
it to NVIDIA’s Cg compiler for compilation to a single executable hardware shader. Only the 
Cg 1.2 language supports mental ray’s shader graph techniques. 


Languages that do not support Cg’s graph feature must implement the entire phenomenon as if 
it were a single shader. 
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3.33.3 Hardwired OpenGL Shaders 


OpenGL 1.x does not support native vertex or fragment shaders, unlike the forthcoming 
OpenGL 2.0 standard. (There are extensions for OpenGL 1.5 that will not be considered here.) 
This means that rendering must entirely rely on C/C++ code in the shader support library, which 
is optional for NVIDIA. The shader prefix for OpenGL is g1-_, and since C/C++ functions in 
shader support libraries have an extra mi prefix, all OpenGL shader function names begin with 
migl_. For example, the OpenGL equivalent of the software shader mib_llum_phong must be 
called miglmibllum_phong. 


Since shader graphs and subshaders are not available for OpenGL, it is not possible to separately 
implement the subshaders of a Phenomenon and have OpenGL 1.4 put them together the way Cg 
can. Instead, mental ray will call the root shader of the Phenomenon, and recursively evaluate its 
subshaders. Here is a sample implementation of an OpenGL shader that implements the software 
material shader mib_illum_phoneg: 


#include "mi_openg1.h" 
extern "C" DLLEXPORT int migl_mib_illum_phong_version(void) { return(2); } 


extern "C" DLLEXPORT miBoolean migl_mib_illum_phong( 


miColor *result, 
mi0gl_render *render, 
struct mib_illum_phong *paras) 
{ 
miColor ambc, ambi, diff, spec; 
miTag *klight ; /* tag of light instance */ 
int m1: /* number of light sources */ 
int i_l; /* offset of light sources */ 
int m; /* light mode: O=all, 1=incl, 2=excl */ 
miScalar expo; /* Phong exponent (cosine power) */ 
ambc = render->eval(&paras->ambience) ; 
ambi = render->eval(&paras->ambient) ; 
diff = render->eval(&paras->diffuse) ; 
spec = render->eval(&paras->specular) ; 
expo = render->eval(&paras->exponent) ; 


*result = diff; 


m = render->eval (&paras->mode) ; 
n_l = render->eval(&paras->n_light) ; 
14 = render->eval (kparas->i_light) ; 


light = render->eval( paras->light) + i_1; 


glLightModeli (GL_LIGHT_MODEL_COLOR_CONTROL, 
GL_SEPARATE_SPECULAR_COLOR) ; 
glLightModelfv(GL_LIGHT_MODEL_AMBIENT, (float *)&ambc) ; 
glMaterialfv (GL_FRONT_AND_BACK, GL_AMBIENT, (float *)&ambi) ; 
glMaterialfv (GL_FRONT_AND_BACK, GL_DIFFUSE, (float *)&diff) ; 


432 3 Using and Writing Shaders 


glMaterialfv (GL_FRONT_AND_BACK, GL_SPECULAR, (float *)&spec); 
glMaterialf (GL_FRONT_AND_BACK, GL_SHININESS, expo) ; 
render->lights_enable(render, n_l, light) ; 


return (miTRUE) ; 


Like for software shaders, a version number is provided. Like software shaders, it is necessary to 
use an mi_eval equivalent since subshaders will be called. These subshaders must return a constant 
value, which will not change for different samples. The extra miOgl_render class that provides 
useful OpenGL support functions is defined by the OpenGL driver library mi_openg1.so, which 
also provides the mi_openg1 .h include file that defines the available methods. 


mi_opengl.so also provides the lights_enable function, which accepts a list of light shader 
instances. It will register these light sources with the OpenGL hardware by calling the light 
shader for each one. These light shaders are also part of the OpenGL shader support library, 
like the material shader. Note that OpenGL hardware generally supports only a small number of 
lights, typically eight. 


extern "C" DLLEXPORT int migl_mib_light_point_version(void) { return(1); } 


extern "C" DLLEXPORT miBoolean migl_mib_light_point ( 
miColor *result, 
mi0gl_render *render , 
struct mib_light_point ¥*paras) 


miColor col = render->eval (&paras->color) ; 
miBoolean atten render->eval (&paras->atten) ; 
const int lgt_idx = render->light_index() ; 


glLightfv(lgt_idx, GL_AMBIENT, black) ; 
glLightfv(lgt_idx, GL_DIFFUSE, (float *)&col); 
glLightfv(lgt_idx, GL_SPECULAR, (float *)&col) ; 


glLightf (lgt_idx, GL_SPOT_CUTOFF, 180.0f) ; 
glLightf (lgt_idx, GL_SPOT_EXPONENT, 128.0f); 


if (miTRUE == atten) { 
GLfloat k = 1.0f / 
(render->eval(&paras->start) + render->eval(&paras->stop) ) ; 
glLightf(lgt_idx, GL_LINEAR_ATTENUATION, k); 
J 


// We need to load the camera transformation, since we are in 
// object space 
glPushMatrix() ; 
glLoadMatrixf (render->cam_trafo()); 
oglLight light; 
if (!render->light_get (&light) ) 
return miFALSE; 
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float pos[4]; 

pos[0] = light.org.x; 

pos[i] = light.org.y; 

pos[2] = light.org.z; 

pos[3] = 1.0f; 

glLightfv(lgt_idx, GL_POSITION, pos); 
glPopMatrix() ; 


*result = col; 
return miTRUE; 


Lights must be set in world space, and the OpenGL driver library provides a method cam- 
trafo that returns the camera matrix which can be loaded on the modelview matrix stack. The 
information about the position, direction and other characteristics of the light can be retrieved 
with the /ight_get method. The current light index can be set and restored with the light_index 
method. 


3.33.4 NVIDIA Cg 1.2 Shaders 


NVIDIA’s Cg 1.2 release introduced interfaces to the Cg programming language, which 
correspond to mental ray’s shader graph and Phenomenon design, and enable mental ray to 
construct a composite Cg shader that corresponds exactly, subshader by subshader, to the software 
shader graph. Cg versions prior to 1.2 are not supported by mental ray. 


In almost all cases, it is sufficient to write only the fragment shader in Cg. If no vertex shader 
is supplied, mental ray supplies a built-in default vertex shader. All illumination calculations are 
performed in the fragment shader. 


Also, Cg shaders do not normally depend on a shader support library the way OpenGL shaders 
do. No C/C++ code is required to use any of the standard Cg shaders shipped with mental 
ray, so no support libraries are supplied. Only the Cg files, named according to the conventions 
described above, such as myphong_f .cg, must be available on the hardware search path (defined 
with ~hardware_path). This makes it very simple to make a third-party Cg shader available to 
mental ray. Each shader must be in a separate file, or pair of files if a vertex shader is required as 
well. 


3.33-4.1 Shader Parameters 


Hardware shaders read their parameters from a set of registers on the graphics board called 
uniform variables, so mental ray needs to know how to copy the shader parameters to the 
uniform variables before the shader is started, and the Cg compiler needs to have a matching 
definition. Here is the Cg syntax for defining shader parameters: 


interface miiBoolean { 
bool eval(vert2frag param) ; 
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¥3 


interface miiInteger { 
int eval(vert2frag param) ; 


te 


interface miiScalar { 
float eval(vert2frag param) ; 


r} 


interface miiVector { 
float3 eval(vert2frag param) ; 
5 


interface miiColor { 
float4 eval(vert2frag p); 
be 


interface miiColorTexture { 


float4 eval(vert2frag param, float3 uv); 


FS 


interface miiMatrix { 
float4x4 eval(vert2frag param) ; 


i 


interface miiLight { 
misLightOut eval(vert2frag param) ; 
}; 
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This is the complete list of available types. For example, the mental ray data type miBoolean is 
declared to the Cg compiler as miiBoolean, implemented as the Cg bool type. The eval function 
tells the Cg compiler that the parameter might be attached to another shader, which must also be 
compiled and downloaded to the graphics board. (Attaching shader outputs to shader parameters 


is how both mental ray and Cg implement shader graphs.) 


Cg shader parameters are declared in the shader code, right in the function body. For example, if 
the software shader declaration is defined in .mi syntax as 


declare shader 
color "myshader" ( 


color "parami", 
scalar "param2", 
vector "param3", 


color texture "param4" 
) 


end declare 
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then it is sufficient to declare these four parameters in the Cg shader body, using the mii* data 
types listed above, using the same names. Note that you can omit parameters from the declaration. 
For example, here is a possible implementation of the shader in Cg: 


struct myshader : miiColor 


{ 
miiColor param! ; 
miiScalar param? ; 
miiVector params ; 
miiColorTexture param4; 
float4 eval(vert2frag p) { 
float4 c = param1.eval(p); 
float s = param2.eval(p); 
float3 v = param3.eval(p) ; 
float4 tex = param4.eval(p, float3(u,v,w)); 
return float4(1,1,1,1); 
} 
}; 


The Cg compiler will be run automatically by mental ray at render time. It will collect all required 
shaders by following the eval links, and create a single binary shader ready for downloading to 
the graphics board. Users only need to supply the Cg source code and leave compilation and 
downloading to mental ray. For more information on the Cg language, see NVIDIA’s Cg 1.2 
compiler reference manual. 


3.33.4.2. Implicit Shader Parameters 


mental ray implicitly supplies several extra parameters for light and material shaders. They are 
automatically downloaded to the fragment shader when matching names are found in the Cg 
declaration. 
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material miLocal2Global | CG_FLOAT4x4 | Matrix for transforming local coor- 
dinates found in vert2frag.position to 
world space. 


light light_origin CG_FLOAT3 Position of the light in camera space 
light_dir CG FLOATS Direction to the light in camera space 
light_spread CG FLOAT Spread angle for spot lights 
light_type CG_INT Type of the light from miLight_type 
light_face CG_INT Illuminate which face of objects: 
O=both, 1=front side only, 2=back- 
side only 


Aspect ratio (height*aspect = width) 
3.33.4.3. Shader C/C++ Support Functions 


GG FLOAT 
CG_FLOAT 
CGFLOAT 


cam_aspect 
cam_aperture 
cam_focal 


Aperture 
Focal (atan(focal/aperture) = field of 
view) 


cam_clip CG_FLOAT2 Clip plane (x=near, y=far) 
cam_size CG_FLOAT2 Resolution of the window 
cam_ortho CG_BOOL Is camera orthographic? 


cam_transfo CG_FLOAT4x4 | Camera transformation 
shdmap_on CG_BOOL Tell if the shadowmap option is on 
for the light 

shdmap-tex[] samplerRECT | Number of shadowmap textures, 1 
for spot and directional lights, 6 for 
point lights 

shdmap-_transfo | CG_FLOAT4x4 | Matrix for transforming 
vert2frag.cPosition to light space 
shdmap_window | CG_FLOAT2 The transformation to apply to UV 
coordinates for perspective and par- 
allel views 

shdmap-size CAs PLAT? The resolution of the shadowmap 
shdmap-bias CG_FLOAT The bias to apply to the shadowmap 


In case a Cg shader is not sufficient, and extra work is needed, a C/C++ support function can be 
supplied in a separate DSO/DLL. Those functions are mostly useful when the information we 
want to pass to the shader is not part of the shader declaration. For example, a noise function 
could compute a lattice data structure and pass it automatically to the shader. The C/C++ function 
name must begin with the prefix micg_. For example, here is a C++ support function for the Cg 
shader nvo_img_intensity: 


extern "C" DLLEXPORT miBoolean micg_nvo_img_intensity ( 


CGparameter *result, 
miCg_render *render, 
miHW_shader *shader) 
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Static bool binit = true; 


if (binit) { 
CreateRandomMap() ; 
binit = false; 


CGparameter sParam = 0; 
CGcontext ctx = render->context_get() ; 


// Create an instance of the shader 
CGtype cgtype = cgGetNamedUserType(render->program_get()) ; 


sParam = cgCreateParameter(ctx, cgtype) ; 
*result = sParam; 


// Set automatically all known parameters from the 

// shader declaration 

int i, nb_param = shader->nbparam_get () ; 

for (i=0; i < nb_param; itt) { 
render->param_eval(sParam, shader->param_get(i)) ; 


} 


// Set the random texture 

CGparameter prnd = cgGetNamedStructParameter(sParam, "random_txt") ; 
cgGLSetTextureParameter(prnd, random_map) ; 

prnd = cgGetNamedStructParameter(sParam, "random_size") ; 
cgGLSetParameterif(prnd, RES); 


return miTRUE; 


This support function installs a Cg shader including parameters, and also loads a texture. 


3.33.4.4 Examples 


Here is a Cg 1.2 implementation of the mib_illum_phong base material shader: 


struct mib_illum_phong : miiColor 


{ 


miiColor ambience, ambient, diffuse, specular; 
miiScalar exponent; 

miiinteger mode; 

miiLight lights[]; 


float4 eval(vert2frag p) 

1 
float4 result; 
float4 lambience = ambience.eval( p); 
float4 lambient = ambient.eval( p); 
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float4 ldiffuse = diffuse.eval( p); 
float4 lspecular = specular.eval( p); 
float lexponent = exponent.eval(p) ; 
float3 vdir normalize(p.cPosition) ; 


result = lambience * lambient; 


// Material calculation for each light 
for (int i=0; i < lights.length; i++) { 
misLightOut light = lights[i].eval(p); 


// Lambert’s cosine law 
if (light.dot_nl > 0) { 
result += light.dot_nl * ldiffuse * light.color; 


// Phong’s cosine power 

float s = mi_phong_specular(lexponent, light.dir, vdir, 
p.cNormal) ; 

result += s * lspecular * light.color; 


} 


return result; 


ie 


Light Shaders work the same way as material shader, but instead of implementing miiColor they 
must implement the miiLight interface: 


struct mib_light_spot : miiLight { 

miiColor color; 
miiBoolean shadow; 
miiScalar factor; 
miiBoolean atten; 
miiScalar start; 
miiScalar stop; 

miiScalar cone; 


// Information from the light instance 


float3 origin; // position of the light 

float3 ldir; // direction of the light 

float spread; // cos angle of the spread 
samplerRECT shdmap_tex[1]; // light shadowmap 

float4x4 shdmap_transfo; // From eye to local light space 
float2 shdmap_window; // size of the window 

float? shdmap_size; // size of the shadowmap 

float shdmap_bias; 


// Evaluation of the light 
misLightOut eval(vert2frag p) { 
misLightOut ret_val; 
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float4 lcolor = color.eval(p) ; 


// same for each light? 
ret_val.dir = normalize(origin - p.cPosition); // vector to light 
ret_val.dot_nl = dot(p.cNormal, ret_val.dir) ; 


// shadow 
if (shadow.eval(p)) { 
float lfactor = factor.eval(p); 


// Shadow coordinates are created form the eye-space 

// position, then compare with the shadowmap 

float4 1Position = mul(shdmap_transfo, float4(p.cPosition,1)); 

float2 shadowUV = (1Position.xy/(-1lPosition.z * shdmap_window) 
+ 0.5) * shdmap_size; 

float4 dist = length(1Position.xyz) ; 


float4 pdepth; 

shadowUV -= 0.5; 

pdepth.x = fitexRECT(shdmap_tex[0], float2(shadowUV.x, 
shadowUV.y)); 

pdepth.y = fitexRECT(shdmap_tex[0], float2(shadowUV.x, 
shadowUV.yt1)) ; 


pdepth.z = fitexRECT(shdmap_tex[0], float2(shadowUV.xt1, 
shadowUV.y)); 
pdepth.w = fitexRECT(shdmap_tex[0], float2(shadowUV.x+1, 


shadowUV.y+1)) ; 


pdepth = pdepth == float4(0,0,0,0) ? dist*2 : pdepth; 

float4 shd = dist - shdmap_bias - pdepth; 

float map_z = dot(shd < float4(0,0,0,0) ? float4(1,1,1,1) 
fioat4(0,0,0,0), float4(1,1,1,1)); 


lcolor.rgb *= lerp(lfactor,1, map_z/4) ; 


// cone 
float d = dot(ret_val.dir, ldir); 
if (d <= 0) { 
lcolor.rgb = 0; 
I 
if (d < spread) { 
lcolor.rgb = 0; 
} 
float lcone = cone.eval(p); 
if (d < lcone) { 
lcolor.rgb *= 1 - (d - lcone) / (spread - lcone) ; 
lcolor = saturate(lcolor) ; 


// dist attenuation 
bool latten = atten.eval(p) ; 
if (latten) { 
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float dist = length(origin - p.cPosition) ; 
float lstop = stop.eval(p) ; 
if (dist >= lstop) { 
lcolor.rgb = 0; 
} else { 
float lstart = start.eval(p); 
fleat t = 1 = (dist = letart) / Cistop = letart); 
lcolor.rgb *= t; 


ts 
ret_val.color = lcolor; 
return ret_val; 


Chapter 4 


Geometry Shaders 


Geometry shaders do not really shade anything, they create scene elements, primarily geometric 
objects. For this purpose, they use a special geometry shader API that is analogous to the 
statements of the .mi scene definition language. This chapter describes this API, and how geometry 
shaders use it. 


Geometry shaders can be used in two places: in instance definitions that reference a shader instead 
of an object, light, camera, or instance group: 


instance "name" 
geometry function 


end instance 


or in phenomena, where they can be attached to the geometry root: 


declare phenomenon 
geometry function 


end declare 


In either case, the geometry shader is evaluated during scene preprocessing before any other 
operation such as rendering starts. The geometry shader is expected to create an object, light, 
camera, or instance group and add the tag of the created element to the result. The result pointer 
passed as its first argument always has the type miTag *, and the shader must be declared as 


declare shader 
geometry "shadername" ("parameter_decl") 


end declare 


442 4 Geometry Shaders 


If result is a null tag, the created element can be returned directly using this pointer, otherwise 
the geometry shader must check whether the type of the item to which result refers is miSCENE_ 
GROUP. If it refers to an instance group, the created entities can be put into this group, otherwise 
the shader must create the group and put the element to which result refers together with the 
entities created by the geometry shader into the instance group. The newly created instance group 
must be returned in result in this case. This ensures that geometry shaders always return either 
an object or an instance group, and that they can be chained such that the end result is a group. 
There is a shader interface function available for adding scene entities to result which takes all the 
above rules into account; refer to mi_geoshader_add_result. 


Creation of geometry requires an altogether different set of shader interface functions. The shader 
is basically doing the same thing that an object or other definition expressed in the .mi language is 
doing, and must have the same functionality available to it. In fact, the shader interface functions 
for geometry shaders closely model the .mi language features: there are begin/end functions for 
most top-level entities and complex sub-entities, and various helper functions to create and attach 
complex information. Many of these return pointers to the created data structures that let the 
geometry shader store primitive data directly without the use of a shader interface function. 


Geometry shaders must include geoshader .h after shader .h. Note that this file is not compatible 
between mental ray 2.1 and mental ray 3.x because a number of features that were introduced 
in mental ray 3.x required extra fields in data structures such as miBox, which in fact 1s called 
miGeoBox in version 3.0 specifically to cause the compiler to flag an error if the old miBox is used. 
This means that geometry shaders compiled for mental ray 2.1 will not, in general, work with 
mental ray 3.x, and vice versa! 


This chapter provides an example and lists all shader interface API functions and data structure 
declarations available to geometry shaders. It does not explain the structure and order of specific 
API calls needed to create a scene. Refer to chapter 2 for the sequence of operations necessary 
to create a scene element, and to appendix A for the correspondence between API calls and the 
entities in the scene description language they create. 


In any case, writing geometry shaders is far more complex than writing another type of shader. 
Although a geometry shader has free run of the entire scene database, and is free to copy-and-alter 
or create any part of it, it is generally a good idea to avoid doing too much with them. Instead, it 
is usually preferable to pass objects, materials, and shaders as input parameters instead of creating 
entire graphs in geometry shaders, although this is possible and sometimes needed in geometry 
shaders used in phenomena. Geometry shaders must never modify existing parts of the scene 
because this will confuse future incremental changes and scene traversal during preprocessing, 
which geometry shaders are part of. Instead, the element to be modified should be passed to the 
geometry shader as a parameter of type geometry, and be used as a template to create a new, 
modified element. 


All geometry shader API calls and data structures may only be used in geometry shaders, not 
any other type of shader. Conversely, no regular shader interface function related to rendering 
may be used in a geometry shader because it is called before rendering begins. Geometry shaders 
are called during the same stage as displacement shaders, but before the displacement shaders of 
objects created by this geometry shader. 
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mental ray 3.0 allows a geometry shader to create a placeholder object that contains no geometry, 
but a bounding box (and optionally a motion bounding box and a maximum displacement), 
and a callback installed with mz_api_object_callback. When mental ray hits the bounding box 
of this placeholder, it will call the callback, which must then build the same object again, only 
this time with the real geometry instead of just installing the callback. Placeholder objects may 
contain only a single object group. This has the advantage that objects are not created unless, 
and when, they are actually needed. When memory runs out, mental ray 3.0 can free up a lot of 
memory by deleting the object — if necessary it can always call the callback again to restore it. 
Finally, If there are several such placeholder objects, and multiple CPUs, mental ray can process 
callbacks in parallel. Placeholder objects are highly recommended for complex geometry that 
would otherwise block a large chunk of memory. 


4.1 Examples 


The following example shader creates an axis-aligned unit cube at the origin. Using unit sizes 
and centering objects at the origin is usually a good idea because the position, orientation, and 
sizes of objects are better adjusted with instances than by hardcoding them into the object. This 
assumes that mental ray is switched to object space mode, which is recommended for all scenes 
anyway (this is done in the options statement). 


#include <shader.h> 
#include <geoshader.h> 
int geocube_version(void) {return(1) ;} 
#define add_vector(X, Y, Z) \ 
v.x = X; v.y = Y; v.z = Z;\ 


mi_api_geovector_xyz_add(&v) ; 


static int vertex_order[] = { 


O56 85, Byer * 
By) 25, Oy: By 
fy By Taos 
1, 0, 4, 7 
}; 
miBoolean geocube( 
miTag *result, 
miState *state, 
miTag «mt 1) /* only one parameter */ 
{ 
int i, k, ix=0; 
mi0bject *obj; 
miGeoVector wv: 
miTag mtl_tag; 


mtl_tag = *mi_eval_tag(mt1l) ; 
obj = mi_api_object_begin(NULL) ; 
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obj->visible = obj->shadow = obj->trace = miTRUE; 
mi_api_basis_list_clear() ; 
mi_api_object_group_begin(0.0) ; 


add_vector(-0.5, -0.5, -0.5); 
add_vector(-0.5, 0.5, -0.5); 
add_vector( 0.5, 0.5, -0.5); 
add_vector( 0.5, -0.5, -0.5); 
add_vector(-0.5, -0.5, 0.5); 
add_vector( 0.5, -0.5, 0.5); 
add_vector( 0.5, 0.5, 0.5); 
add_vector(-0.5, 0.5, 0.5); 


for (i=0; i < 4; i++) 
mi_api_vertex_add(i) ; 


for (i=4; i < 8; i++) 
mi_api_vertex_add(i); 


for (i=0; i < 16; i++) 
mi_api_vertex_add(vertex_order [i]); 


for (i=0; i < 6; it+) { 
mi_api_poly_begin_tag(1, mtl_tag) ; 
for (k=0; k < 4; k++) 
mi_api_poly_index_add(ix++) ; 
mi_api_poly_end() ; 
Z 
mi_api_object_group_end() ; 
return(mi_geoshader_add_result (result, 
mi_api_object_end())); 


The next example creates a trimmed B-Spline free-form surface. There is one trimming curve 
defined which is used as a hole curve to cut a square hole out of the surface. It also shows how a 
texture surface can be added to a surface. 


#include <shader.h> 
#include <geoshader.h> 


int bspline_surface_version(void) { return 1; } 


miBoolean bspline_surface( 


miTag *result, 

miState *Sstate, 

void *paras ) /* no parameters used */ 
{ 

int re 

mi0bject *obj; 


miGeoScalar knot; 


4.1 


Examples 


miDlist 


miGeoRange 


miApprox 


miTag 


*xparams, *uparams, *vparams; 
range; 

approx; 

otag; 


miVector cp[] = { 


fe oomme 16 surface control points */ 
10, 2. Oo eta 216422) OF5. $835 25° OP, 
10, 3, OF, 11, 3, ifs Tay 3, Ake te, 3°07 
40, 4, OF. U1, 4. i. 12,2 oe 4s. 12, 4 BS, 
10, 5, O},; G/F: 22.600}, 43, 55. OF, 
ft aes 4 (2d) curve control points */ 
{0.4, 0.4, 0}, {0.6, 0.4, O}, 
10,6, 0.6, 0}, 10.4, 0.65 OF; 
ft => 4 (3d) texture surface control points */ 
cu, 0, OF, 44, 0, Oy 10, Ty OF. 434°5,7 OF 
miGeoScalar curve_knots[] = {0, 1, 2, 3, 4}; 
miUint curve_v [] = {16, 17, 18, 19, 16}; /* closed loop */ 
miUint texsurf_v iT]. = {20;-21.. 22,. 23}: 
miGeoScalar tex_uknots [] = {0.0, 1.0}; 
miGeoScalar tex_vknots [] = {0.0, 1.0}; 


[* *RRRKKKKKKKK Create Object *kKKKKKKKKKK */ 


obj = 


obj->visible = 


mi_api_object_begin (NULL) ; 


obj->shadow = obj->trace = miTRUE; 


mi_api_basis_list_clear() ; 
mi_api_basis_add(mi_mem_strdup("bspline_3"), 


miFALSE, miBASIS_BSPLINE, 3, 0, 0); 


mi_api_basis_add(mi_mem_strdup("bezier_1"), 


miFALSE, miBASIS_BEZIER, 1, 0, 0); 


mi_api_object_group_begin(0.0) ; 


/* control points and references */ 
for(i=0; i < 24; i++) 


mi_api_vector_xyz_add(&cp[i]) ; 


for(i=0; i < 24; i++) 


mi_api_vertex_add(i) ; 


[/* *KEKKKKAKKAK Create trim-Ccurve ****K*KKKKKKK */ 


mi_api_curve_begin(mi_mem_strdup("curve_0"), 


mi_mem_strdup("bezier_1"), miFALSE) ; 


/* curve knot sequence */ 
params = mi_api_dlist_create(miDLIST_GEOSCALAR) ; 
for(i=0; i < 5; i++) 


mi_api_dlist_add(params, &curve_knots[i]); 


/* curve control point references, 
non-rational (w=1) */ 
for(i=0; i < 5; i++) 


mi_api_vertex_ref_add(curve_v[i], 1.0); 
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mi_api_curve_end (params) ; 


/* *KEKKKKKKK Create free-form surface ******K*K*KKK */ 
mi_api_surface_begin_tag(mi_mem_strdup("surf_0"), 0); 


/* create the uv knot vectors for the (bezier) surface */ 
for (k=0; k < 2; k++) { 
params = mi_api_dlist_create( 
miDLIST_GEOSCALAR) ; 
knot = 0.0; 
for(i=0; i < 4; i++) 
mi_api_dlist_add(params, &knot) ; 
knot = 1.0; 
for(i=0; i < 4; i++) 
mi_api_dlist_add(params, &knot) ; 
mi_api_surface_params(k == 0 ? miU : miV, 
mi_mem_strdup("bspline_3"), 
O., 1., params, miFALSE) ; 


/* control point references, nonrational(w=1) */ 
for(i=0; i < 16; i++) 
mi_api_vertex_ref_add(i, 1.0); 


[/* *eREKKKKKKKKK add a texture surface ***KKKKKKKK */ 
uparams = mi_api_dlist_create(miDLIST_GEOSCALAR) ; 
for (i=0O; i < 2; i++) 

mi_api_dlist_add(uparams, &tex_uknots[i]); 
vparams = mi_api_dlist_create(miDLIST_GEOSCALAR) ; 
for (i=0; i < 2; i++) 

mi_api_dlist_add(vparams, &tex_vknots[i]); 
mi_api_surface_texture_begin(miFALSE, /* is_volume */ 


miFALSE, /* is_bump */ 
mi_mem_strdup("bezier_1"), 
uparams, 

miFALSE, /* v_rational */ 
mi_mem_strdup("bezier_1"), 
vparams, 

miFALSE) ; /* v_rational */ 


/* texture surface control point references, nonrational */ 
for(i=0; i < 4; it+) 
mi_api_vertex_ref_add(texsurf_v[i], 1.0); 


/* define one hole curve on the surface */ 

range.min = 0.0; 

range.max = 4.0; 

mi_api_surface_curveseg(miTRUE, /* new loop */ 
miCURVE_HOLE, 
mi_mem_strdup("curve_0"), 
&range) ; 
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mi_api_surface_end() ; 


/* set approximation method for the surface */ 
miAPPROX_DEFAULT (approx) ; 

approx.method = miAPPROX_CURVATURE; 

approx.cnst [miCNST_DISTANCE] = 0.01; 
mi_api_surface_approx(mi_mem_strdup("surf_0"), &approx) ; 


/* set approximation method for the curve */ 
miAPPROX_DEFAULT (approx) ; 

approx.method = miAPPROX_PARAMETRIC; 

approx.cnst [miCNST_UPARAM] = 1; 
mi_api_curve_approx(mi_mem_strdup("curve_0"), &approx) ; 


mi_api_object_group_end() ; 
otag = mi_api_object_end() ; 
return (mi_geoshader_add_result (result, otag)); 


The next example accepts an object as input, and creates a new object based on the input object. 
The new object is identical to the old one except that only points in space are copied and all 
normals, texture vectors, motion, and other information is ignored. Also, it deals with groups 
correctly only if it does not contain multiple local spaces because it ignores the transformation 
matrices in the instance loop. 


#include <assert.h> 
#include "shader.h" 
#include "geoshader.h" 


int facet_version(void) {return(1) ;} 


static miBoolean box_to_object( 


miTag *result, 
miGeoBox *box) 
4, 
int i, vs = box->vert_info.sizeof_vertex; 


miQbject *Oobj; 
miGeoIndex *xvert = miBOX_GET_VERTICES (box) ; 
miTriangle *tri miBOX_GET_PRIMITIVES (box) ; 


assert (box->type == miBOX_TRIANGLES) ; 

obj = mi_api_object_begin(NULL) ; 

obj->visible = obj->shadow = obj->trace = miTRUE; 
mi_api_basis_list_clear() ; 
mi_api_object_group_begin(0.0) ; 


for (i=0; i < box->vect_info.no_points; i++) 
mi_api_vector_xyz_add(box->vectors + i); 


for (i=0; i < box->no_vertices; i++, vertt=vs) 
mi_api_vertex_add(*vert) ; 
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/* the +=2 increment omits every other triangle */ 

for (i=0; i < box->no_primitives; i++, trit+t=2) f 
mi_api_poly_begin_tag(1, 0); 
mi_api_poly_index_add(tri->a) ; 
mi_api_poly_index_add(tri->b) ; 
mi_api_poly_index_add(tri->c) ; 
mi_api_poly_end(); 

} 

mi_api_object_group_end() ; 

return (mi_geoshader_add_result(result, mi_api_object_end())); 
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5 
miBoolean facet ( 
miTag *result, 
miState *State, 
miTag *param) 
{ 
miTag leaves, scan, boxes, next; 
miBoolean ret; 
ret = mi_geoshader_tesselate(state, &leaves, *mi_eval_tag(param) ) ; 
for (scan=leaves; scan; scan=next) { 
miInstance *inst = mi_db_access(scan) ; 
/* 
* in mental ray 3.0, the loop is unnecessary, 
* box->next_box will always be a null tag 
* / 
for (boxes=inst->boxes; boxes; boxes=next) { 
miGeoBox *box = mi_db_access (boxes) ; 
ret &= box_to_object(result, box); 
next = box->next_box; 
mi_db_unpin (boxes) ; 
} 
next = inst->next; 
mi_db_unpin(scan) ; 
} 
mi_geoshader_tesselate_end (leaves) ; 
return(ret) ; 
} 


The main facet shader first tessellates the input geometry. This builds a leaf instance list containing 
a sequence of instances that contain both an item field pointing to the source geometry (which 
may be difficult to handle because it may include many different types of complex free-form 
surface and polygonal geometry), and a boxes field that points to triangles. Without mi_geoshader_ 
tesselate, the boxes field may be empty, and the shader would have to do its own traversal to find 


the instances. 


The following nested loops consider all instances, and all boxes in each instance. There are 
multiple instances if the input object passed to the shader as its only parameter is an instance 
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group. In mental ray 2.1, an instance may contain multiple boxes if the object has too many 
vectors, vertices, or triangles to fit into a single box. mental ray 3.x always generates a single 
box for each instance. For each box, a new object is generated by calling box_to_object, which is 
similar to the previous example except that it gets its information from a box. Every new object 
is appended to the result using m1_geoshader_add_result. 


Finally, the shader calls mi_geoshader_tesselate_end to release the instance list, including all triangle 
boxes, that was created by mi_geoshader-tesselate. This is important because this list may be very 
large, and would introduce a large memory leak if not freed. 


This example works only for mental ray 3.0. To make it work with mental ray 2.1, change 
miGeoBox to miBox, and miGeoIndex to miIndex. The reason for this change is that mental ray 
3.0 must always pack all geometry in a single box to build a nondiverging dataflow dependency 
graph, so the box had to be extended to handle arbitrary amounts of geometry. 


Here is a scene that uses the facet shader in the third example. It assumes that the shader was 
compiled to a library named facet.so. 


link "base.so" 
link "facet.so" 
$include <base.mi> 


declare shader 
geometry "facet" (geometry "obj") 
version 1 

end declare 


options "opt" 
samples 0 2 
object space 

end options 


camera "cam" 


output "Seo" “x. Feb" 
focal 50 

aperture ft 

aspect 1 

resolution 500 500 


end camera 


instance "cam_inst" "cam" 
transform 0.7719 0.3042 -0.5582 0.0 
0.0000 0.8781 0.4785 0.0 
0.6357 -0.36935 0.67fs 0.0 
0.0000 0.0000’ -26.000 1.0 
end instance 


light “lighti" 
“nib Jient- point’ ("eoler”. Pa 14 
origin 00 0 

end light 
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instance "lighti_inst" "lighti" 
transform -  -O..o 
Oo. 4:0 
0 0 1 Q 
“20 ~S0.-20 1 
end instance 


material "mtl" opaque 
"mib_illum_phong" ( 
"exponent" 50, 


"ambient" 0.5 0.5 0.65, 
"dittnee” «Out Ont Oct, 
“specular” 4.0, 1.0, 1.0, 
"ambience" 0.3 0.3 0.3, 
"lights" ["lighti_inst"] 


) 


end material 


object "sphere" visible shadow trace tag 1 
basis "bs" bspline 3 


group 

0.0000 5.0000 0.0000 0.7957 5.0000 1.3781 
-0.7956 5.0000 1.3781 -1.5913 5.0000 0.0000 
-0.795f 5&.0000 -1.3781 0.7956. &.0000 -1.3/81 

1.5913 5.0000 0.0000 2.3448 3.9181 4.0613 
-2.3448 3.9181 4.0613 -4.6896 3.9181 0.0000 
-2.3448 3.9181 -4.0613 2.3448 3.9181 -4.0613 
4.6896 3.9181 0.0000 3.3276 0.0000 5.7636 
=3.3276 0.0000 5.7636 -6.6552 0.0000 0.0000 
-3,.a216 0.0000 -5. 7636 3.3276 0.0000 -5.7636 

6.6552 0.0000 0.0000 2.3448 -3.9181 4.0613 
-2.3448 -3.9181 4.0613 -4.6896 -3.9181 0.0000 
-2.3448 -3.9181 -4.0613 2.3448 -3.9181 -4.0613 
4.6896 -3.9181 0.0000 0.7957 -5.0000 1.3781 
-~0,7956 -5.0000 1.37391 -1.5913 -5.0000 0.0000 
=0,.795f -6.0000 -1.35/761 0.7956 -5.0000 -1.3781 

1.5913 -5.0000 0.0000 0.0000 -5.0000 0.0000 
v 0 vod v2 v 3 v4 v 5 v 6 7 
v 8 v 9 v 10 7 43 v 12 v 13 v 14 v.45 
v 16 v 17 v 18 v 19 v 20 v 21 v 22 v 23 
v 24 ¥ 25 v 26 v 27 v 28 v 29 v 30 v ol 
surface "surf" "" 

“oe” 0 6 sa Pe eo Ts oso. 


g« Oar ech. Oy Ts 
"bs" 0 4 O., On. -@: L. 2. By 4 4s 4s. Se 
31 3131 31 31 31 31.31 31 26 25 30 29 28 2f 26 
25 30 20 19 24 23 22 21 20 19 24 14 13 18 17 16 
16 14.33 18 8 f 1241 20 8,.8..f i2:,2.1 6 
5 43 2160000 0 0 0 0 0 
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approximate surface parametric 11 "surf" 
end group 
end object 


instance "sphere_insti" "sphere" 


material “wei” 
transform 1 2 2 2D 
uy Ge 
0. @ Awe 
“6 Ue ee 
end instance 
instance "sphere_inst2" 
geometry "facet" ("obj" "sphere") 
material sy a 
transform So OU 8 
te 
Oh. re Br 
peo. OY s 


end instance 


instgroup "rootgrp" 
"cam_inst" "lighti_inst" "sphere_insti" "sphere_inst2" 
end instgroup 


render "rootgrp" "cam_inst" "opt" 
Here is the resulting image when this scene is rendered. The smooth sphere on the right is the 


original sphere, which got passed to the facet example shader to generate the front sphere. The 
shader has copied every other triangle of the sphere but omitted the normals. 
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4.2 Geometry Shader API 


This section describes the high-level API which provides an easy-to-use scene definition layer 
for geometry shaders. The high-level API functions are mainly concerned with atomic creation 
of high-level elements like those found in the .mi2 language. Many such elements, especially 
geometric objects, are built from multiple scene database entries with numerous internal 
references. This internal complexity is hidden by the API module and expanded automatically. 
However, simple elements such as cameras are created by API calls but filling in certain parameters 
requires struct member assignment. To simplify the API call interface, API calls that would do 
nothing but assign a variable to another have been omitted. 


Conceptually, database storage is performed on four layers: 


1. At the lowest level, MEM is handling plain unstructured memory allocation on a single 
host, identified by pointers. 
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2. The DB layer on top of MEM provides network-wide global shared memory identified by 


tags, and maintains type information. 


3. The SCENE layer adds structure to DB memory blocks, and provides operations on typed 
data including default values and graph structuring operations. 


4. At the top level, the API module provides a high-level object-based scene creation and 
rendering service based on symbolic names. 


This section should be read in conjunction with the section 4.3, which describes simple data 
structures that the API module requires assignments to. For example, API contains functions to 
begin and finish the creation of a camera, but provides no functions for setting each of the many 
fields of these structures. Instead, they are simply written to the fields directly. 


The API module has been patterned after the .mi2 language, to the point where the .mi2 yacc 
grammar consists almost entirely of one or very few API calls or variable assignments for every 
statement and clause. To understand the correct order of API calls, refer to the .mi2 language 
description (page 59). The complete yacc grammar that parses the .mi2 language, including C 
code, is reprinted in appendix B. For information on the syntax of a yacc grammar description, 
refer to the Unix manual page for yacc. 


Note that all character string arguments passed to any of the API functions below are expected to 
have been allocated with mi_mem_allocate or, more commonly, mi_mem_strdup. All API functions 
release such strings using mi_mem_release, so the same allocated string may not be passed to API 
twice. Similarly, miDlists created with mz_api_dlist_create and passed as an argument to an API 
call are freed by API, and should not be passed to API twice. The reason for this is that API keeps 
most strings for extended periods of time, so allocation is almost always necessary somewhere, 
and putting the burden on the API caller avoids double allocations in cases where the caller works 
with allocated strings anyway (for example in yacc parsers). In the few cases where API could 
work with non-allocated strings (mi_api_debug, for example) allocation is required anyway to 
avoid requiring allocation for some strings but not others, which would invite hard-to-find bugs. 
Functions whose name does not begin with mi_api_ generally do not require string allocation. 


Most API functions return a boolean, a pointer, or a tag. If the function succeeds, miTRUE, a 
non-null pointer, or a non-null tag is returned, respectively. If an error occurs, miFALSE or a null 
pointer or tag is returned; this means that errors can be caught with C’s “!” operator. The tags 
returned by the calls whose names end in _end are merely a convenience; they are not generally 
useful to standard name-based translators. 


Note that many of these functions come in begin and end pairs, such as mi_api_object_begin and 
mi_api_object_end. These calls may not be interleaved in any way; there may only be one open 
unfinished begin ... end bracket at any time in a single thread. (Multiple threads can have such an 
open bracket each.) 


4.2.1 Symbol Tables 


The API module identifies all entities by name. Different name spaces are provided for different 
purposes. In particular, the API module supports both the .mil and .mi2 languages, which have 
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a different name space concept. The .mi2 module uses a shared global name space for all element 
types, while the .mil format uses separate name spaces for each element type. 


Note that shader parameter names do not use a persistent name space and have no assigned 
symbol table. Shader parameters are stored in declarations and are not accessible in any symbol 
table. There are also other short-lived sub-entities such as curves or surfaces that are not stored 
in symbol tables. 


In general, symbol tables are used by the API module internally only. There is normally no need 
for another module to access specific symbol tables. However, API provides lookup functions 
for symbol tables that return the tag for individual named entities. This can be used for accessing 
the tessellated renderable representation of a geometric object, or for applying low-level scene 
access functions to entities created with API functions. 


For example, the API module can be used to set up a small scene consisting of a single free-form 
surface object, which is then “rendered” using a render function that does not call any renderer, 
but uses the symbol table to find the object’s tag, accesses the tessellated geometry, and displays 
a wireframe of the tessellation in a GUI window. This is a useful application of API because it 
visualizes the effects of user-defined approximation modes. 


The following table lists the symbol tables. All symbol tables except the first three in the table 
below are used for .mil entities (bracketed by frame and end frame statements) only; .mi2 
entities except declarations are put into the global table instead. The reason for this separation 
is that mental ray 2.x and higher put all scene entities into a single name space. For example, 
a material and an instance cannot both have the same name. Only declarations have a separate 
namespace because they are named after C/C++ shader names, which are not scene entities. This 
makes it possible to have shader parameters of type geometry that can be arbitrarily assigned 
any geometric scene entity, or instances that accept objects, lights, cameras, or groups without 
ambiguity. 


S-GLOBAL all .mi2 entities 

S-FUNCDECL | Function declarations (declare statements) 
S-VARIABLE For internal use only 

S-OPTIONS Options (options statements) 
S-CAMERA Cameras (camera statements) 

S_LIGHT Lights (light statements) 


S-OBJECT Geometric objects (object statements) 
S_INSTANCE Instances (instance statements) 
S_INSTGROUP | Instance groups (group statements) 
S-MATERIAL Materials (material statements) 
S-CTEXTURE | Color textures (color texture statements) 
S_STEXTURE Scalar textures (scalar texture statements) 
S-VTEXTURE | Vector textures (vector texture statements) 


API defines a number of specialized functions that perform lookups required during parsing: 
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miTag mi_api_name_lookup( 
char * name ) 


Look up the element name in the .mi2 element and function declaration symbol tables (S_GLOBAL 
and S_FUNCDECL, and return the tag if found. Otherwise, return a null tag. Other symbol tables 
are not searched because .mil elements are temporary and disappear when the current frame ends. 


miTag mi_api_decl_lookup( 
char * name ) 


Same thing but just for shader declarations. This is a separate function because if an object and a 
declaration have the same name (this is legal because they are in different name spaces), mi_api- 
name_lookup will never see the declaration and always return the other object. 


miBoolean mi_api_variable_set ( 
char *name , /* variable name */ 
char *value) /* value or 0 to unset */ 


Set a variable name to a value value. If value is a null pointer, delete the variable. Variables can 
be redefined. The main purpose is to store meta-data in .mi scene files using the set command 
for variables such as author, translator, creation date, etc, whose values can be picked up by the 
client application or even a shader. 


const char *mi_api_variable_lookup( 
char *name ) /* variable name */ 


Return the value of the variable name, as set with a preceding mi_api_variable_set. If the variable 
is not defined, a null pointer is returned. The returned string should not be modified or released. 


const char *mi_api_tag_lookup( 
miTag tag) 


This is a reverse lookup function. Given a tag, it scans all symbol tables for an element with this 
tag and returns its name. This function is intended for printing more helpful error messages if 
only a tag is known, and to allow database dumps containing names. If the tag cannot be found, a 
null pointer is returned. A non-null pointer should not be modified or released, it points directly 
into the symbol table. 


miTag mi_api_light_lookup( 
char *xname ) /* instance to look up */ 
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*-1T ook up a light by name and return its tag. If no light by this name is found, return a null tag. 
This function is obsolete and supported only to access old .mil (mental ray 1.9) scenes; use mz_ 
apiname_lookup instead. 


miTag mi_api_material_lookup( 
char *xname ) /* material to look up */ 


?-1T ook up a material by name and return its tag. If no material by this name is found, return a 
null tag. This function is obsolete and supported only to access old .mil (mental ray 1.9) scenes; 
use m1_api_name_lookup instead. 


miTag mi_api_texture_lookup( 
char *name, /* texture to find */ 
int type) /* O=col, 1=scal, 2=vec */ 


?-1T ook up a texture by name and return its tag. If no texture by this name is found, return a null 
tag. type is the desired texture type: 0 for color textures, 1 for scalar textures, and 2 for vector 
textures. This function is obsolete and supported only to access old .mil (mental ray 1.9) scenes; 
use mi_api_name_lookup instead. 


miBoolean mi_api_surface_lookup ( 


char *xname , /* name of face */ 
miTag *xinstance, /* instance with face */ 
miGeoIndex *idx) /* index of face */ 


Look up a surface by name and return its tag. If no surface by this name is found, return miFALSE, 
otherwise return miTRUE. This function can be used only while defining a geometric object 
group, between mi_object_group_begin and mi_object_group_end. Its purpose is finding surfaces 
to be connected for connection statements. The surface instance tag (not currently used) and the 
surface index (a sequential number beginning with 0 in every object that enumerates the surfaces 
in the object) are also returned. 


void *mi_api_curve_lookup( 


char *xname , /* existing curve */ 
enum miCurve_type type, /* type of curve */ 
miBoolean newloop, /* is this a new loop */ 
miGeoRange *xrange, /* range of the curve */ 
int *no_scalars) 


Look up a curve by name and type and return an identifying pointer. If no curve by this name is 
found, return a null pointer. The curve type is one of miCURVE_TRIM, miCURVE_HOLE, and miCURVE_ 
SPECIAL, as defined by the SCENE module. This function is used when a surface references a 
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curve as a trim, hole, or special curve with the given range. This function not only looks up 
the curve, but also creates a new curve reference entry containing the curve identifier, the type, 
whether this curve begins a new loop or continues an old one (newloop), and the parameter 
range of the curve to use. The number of parameters of the curve is returned in *no_scalars. This 
function may only be used during the definition of a surface. Because of the side effects, this is 
not a true lookup function. 


miTag mi_api_camera_end (void) 


Complete the definition of the camera, after all parameters have been adjusted. If an error occurs, 
a null tag is returned; otherwise the tag of the new camera element is returned. The type of the 
returned element is miSCENE_CAMERA. 


miBoolean mi_api_output_colorprofile( 
char *cprof_name) 


remembers the named color profile for later use. The color profile is used to convert the color 
frame buffer to the requested color space while writing it to a file. The routine has to be called 
before mi_api_output_file_def is invoked. The transformation will only be performed if a color 
profile for the rendering color space has also been provided. The memory associated with the 
function parameter is released by the routine. 


miTag mi_api_output_file_def ( 


miUint typemap, /* data type bitmap */ 
miUint interpmap, /* interp req bitmap */ 
char *format, /* file type string */ 
char *fname) /* file name */ 


Define an output file and return an output function describing the file to write. The returned 
function has a special type code that tells mz_api_output-_shaders to write a file instead of calling 
an output shader, and has the given format and file name encoded in its parameter area. It is not 
a normal shading function but can be treated as one by the caller, and can be appended to the 
camera’s output function list. 


When the output list is evaluated after rendering, this definition will write a frame buffer to 
the named file fname, using the file format format. Valid formats are extension strings such as 
"rgb" or "rla"; refer to the user’s manual for a complete list. The typemap is a bitmap’. Valid bit 
numbers are defined by the milmg_type enum as defined by the IMG module. Each bit informs 
the renderer that this shader requires a frame buffer of this type; at rendering time all active 
bitmaps (those defined in the camera used for rendering) are OR-ed. Only one bit should be set. 

'Until mental ray 3.2, all bitmaps were miUlong instead of miUint, which was equivalent to an unsigned 32-bit integer. 


mental ray 3.2 made miUlongs 64 bits on all 64-bit platforms, regardless of Microsoft’s ill-advised 32-bit long in 64-bit 
Windows. For the shader writer, nothing changes. 
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The interpmap bitmap uses the same pattern as typemap. It has a bit set if the frame buffer 
described by the corresponding set bit in typemap should be interpolated. 


miBoolean mi_api_output_file_parameter ( 


miTag function, /* output file function */ 
miInteger code, /* parameter value code */ 
void *value) /* parameter value pointer */ 


Supply one parameter value identified by its code to an output file function. The function tag 
identifies the output file function returned by a call to mi_api_output_file_def. The output file 
function is able to store 8 float parameter values. The code determines which one of these values 
will be changed. The actual meaning of a parameter value is not predefined and depends on the 
file format used. Currently, the miIMG_FORMAT_JPEG format interprets the first parameter value 
as compression quality. 


miTag mi_api_output_function_def ( 


miUint typemap, /* data type bitmap */ 
miUint interpmap, /* interp req bitmap */ 
miTag function) /* output shader */ 


Define an output shader. Like output files, output shaders require a typemap. Unlike output filles, 
output shaders may have multiple bits set. The function tag identifies the shader to be called. 
Shader tags are obtained during shader definition, they are returned by mi_api_function_call_end. 
The returned function tag can be appended to the camera’s output function list by the caller. 


The interpmap bitmap uses the same pattern as typemap. It has a bit set if the frame buffer 
described by the corresponding set bit in typemap should be interpolated. 


miBoolean mi_api_output_file_override( 
char *format, 
char *fname) 


Specify a file type and a file name that overrides the corresponding arguments of the next mi_ap1- 
output_file_def call. This call is not normally used to define a scene; it is intended for command- 
line option parsers that accept overrides for the file type and name specified in the scene. The 
override function must be called before the call to m1_api_output_file_def whose arguments should 
be overridden. 


miBoolean mi_api_output_type_identify ( 
miUint *xtypemap, /* type bitmap */ 
miUint *kinterpmap, /* interp bitmap */ 
char *xtypename) /* data type */ 
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This function converts a type string to a type map as required by the output file and output 
shader definition functions above. A type string is a comma-separated list of types, such as 
"rgba,n,contour". The special type contour is accepted also; it is the only one that is handled 
by RC only and not by IMG. All other types are identified in the same way as done by miimg_ 
type_identify. The type bitmap is returned in *typemap; the bits correspond to 1 shifted left by 
the mi IMG_TYPE_* code. 

Types can be prefixed with ‘+’ or ‘-’ to turn interpolation on or off for the frame buffer, 
respectively. Interpolation means that unsampled pixels get a value interpolated from its 
neighbors, rather than becoming a copy of one of its neighbors. Interpolation is on by default 
for all kinds of color frame buffers and off for all others. The interpolation bitmap is returned in 
*interpmap; the bit layout is the same as for *typemap. 


miBoolean mi_api_output_imfdisp_handle( 
miTag camera_tag) /* camera tag */ 


?-! This function should be called after all output files have been defined. For every output file in 
the camera’s output list of camera specified by camera_tag, a 128-byte file is created, containing 
the image resolution and the gamma factor from the camera, as well as information about how to 
open a socket to mental ray and version information. This information is understood by programs 
such as imf_disp which can connect to mental ray during rendering and show the rendered image 
as it is being created. Note that mental ray, when connected to in this way, will always transfer 
the RGBA picture regardless of the type of the file used to establish the connection. mental ray 
3.x does not require calling this function. 


miBoolean mi_api_output_list ( 
miTag cam_tag) /* camera tag */ 
miTag opt_tag) /* options tag */ 


This function calls mi_phen_output_list, which collects all the type maps from the output list in 
the given camera and places appropriate frame buffer records into the options structure specified 
by tag. This function is no longer used; RC calls miphen_output_list directly after output shaders 
introduced by phenomena have been added. mi_api_output_tlist may be removed in a future 
version of mental ray because it doesn’t take phenomena into account, which means it generates 
incomplete frame buffer lists. 


miBoolean mi_api_output_shaders ( 


miTag cam_inst_tag, /* camera inst */ 
miTag opt_tag, /* options tag */ 
miTag * images) /* frame bufs */ 


?-'This function is obsolete since output shaders are called from mi_rc_render. Therefore it prints 
a warning and always returns miTRUE. The output list remains unchanged in the process. 
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miBoolean mi_api_framebuffer ( 


miOptions *opt, /* set framebuffer here */ 
int ns /* frame buffer 0..7 to set */ 
char *ktype) /* frame buffer type: "+rgba" etc */ 


This function sets or clears the definition of a user-defined frame buffer. There are up to eight 
user frame buffers numbered 0 through 7. Each can have an arbitrary user-defined type. The same 
types as for output statements are available, such as +rgba, -z, m, etc. As for output statements, 
“+” indicates sample interpolation and “-” indicates padding. If the type is a null pointer, the 
frame buffer is deleted from the options. Shaders can access these frame buffers with the m_fb_ 
get and mi_fb_put functions. The limitation to eight frame buffers has been removed in mental 
ray 3.4. 


miTag mi_api_pass_save_def ( 


miUint typemap, /* data type bitmap */ 

miUint interpmap, /* interpolation req bitmap */ 

int max_samples, /* opt. max samples to write, or 0 */ 
char *out_fn) /* output pass file name */ 


°-! The pass list in a camera is largely analogous to the output list, and uses similar functions. 
However, each statement is not concerned with writing pass files and calling preprocess or merge 
functions. This statement implements the pass write statement. Like output statements (and 
mi_api_output.*_def calls), the order is significant; each *_def call appends another statement 
to the script that is executed in order after rendering. Assuming that cam is a pointer of type 
miCamera, pass statements can be created with code like this: 


cam->pass = mi_api_function_append(cam->pass, mi_api_pass_*_def(...)); 


The typemap defines which frame buffers should go into the pass file. In mental ray 3.1 and 3.2, it 
is used only to enable these frame buffers but does not exclude other rendered frame buffers from 
being written to the file; all rendered frame buffers will be written. The color and depth frame 
buffers are always rendered and written if there are pass statements. The imterpmap specifies 
which frame buffers in the typemap should be interpolated (have the + sign in the type list in the 
pass statement). 


The max_samples value controls the number of samples per pixel to write to the pass file. It 
is equivalent to max_samples in the camera (miCamera), but allows resampling of the rendered 
image to write pass files with fewer samples than rendered. Specifying a higher sampling for the 
pass file than in the camera is not useful. A value of 0 will use the camera’s max_samples. Negative 
values are not allowed. 


Finally, out_fn is the name of the pass file to write. 
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miTag mi_api_pass_prep_def ( 


miUint typemap, /* data type bitmap */ 

miUint interpmap, /* interpolation req bitmap */ 

int max_samples, /* opt. max samples to write, or ~0O */ 
char *in_fn, /* input pass file name */ 

char *xout_fn, /* output pass file name */ 

miTag function) /* pass preprocessing function */ 


>2 This function defines a pass preprocessing function in the camera. The typemap, interpmap, 
and max-_samples arguments are similar to mi_api_pass_save_def arguments. This function also 
specifies the pass file name in_fn to read from, the function to execute, and the pass file name out- 
fn to write to. The function must be a tag of a miFunction that is created like any other shader, 
using mi_api_function_call and related calls. A pass preprocessing function is a shader that has 
read access to a single pass file and write access to another single pass file, and can access any 
sample in random order by sample raster coordinate. 


miTag mi_api_pass_merge_def ( 


miUint typemap, /* data type bitmap */ 

miUint interpmap, /* interpolation req bitmap */ 

int max_samples, /* opt. max samples to write, or 0 */ 
miDlist *in_fn_list, /* input pass file name list */ 

char *xout_fn, /* output pass file name, or 0 */ 
miTag function) /* pass preprocessing function */ 


>2 This function defines a pass merge function in the camera. The arguments are analogous to mi_ 
api_pass_prep_def, except that the input file name is replaced with an input file name list, which 
is a dynamic list containing strings. Dynamic lists can be created with the mz_api_dlist_create 
(miDLIST_POINTER) and mi_api_dlist_add with a mi_mem-_strdup’ed string. It is not necessary to 
release the dynamic list. Pass merge functions are shaders that have access to any number of input 
pass files, one output pass file, and only one sample coordinate at a time. 


miTag mi_api_pass_delete_def ( 
char *fn) /* pass file name to delete */ 


°-2 This function defines a delete instruction in the camera. It simply deletes the file fn. This is 
useful to clean up temporary pass files after they have been preprocessed or merged, to avoid 
leaving very large files behind after rendering and pass processing finishes. Note that any file can 
be deleted with this statement, but it is not recommended to have a pass script consisting of a 
single delete instruction in order to delete, say, an unnecessary image file — the existence of any 
pass statement, even if it just a delete, will put mental ray into pass mode, which will enable an 
obligatory depth frame buffer and disable certain optimizations such as blank window rectangle 
elimination. 


462 4 Geometry Shaders 


4.2.2 Cameras and Options 


miCamera *mi_api_camera_begin( 
char *name ) /* light name */ 


Begin the definition of a camera with the specified mame. A pointer to the camera is returned; the 
caller may modify the structure. 


miBoolean mi_api_camera_end (void) 
Complete the definition of a camera after all parameters have been set. 


miQOptions *mi_api_options_begin( 
char «name ) /* light name */ 


Begin the definition of an options block with the specified name. A pointer to the options block 
is returned; the caller may modify the structure. 


miBoolean mi_api_options_end(void) 
Complete the definition of an options block after all parameters have been set. 


miBoolean mi_api_taglist_reset (void) 
miTag *xtag, /* tag to reset */ 
miDlist *xlist) /* list of tags */ 


>> Create a tag list database element from the dynamic list /ist, and store the new tag in “tag. If 
tag points to a non-null tag, that tag is assumed to have been created from a previous call to mz- 
api_taglist_reset, and is deleted. The /ist is assumed to have been created with a call like mi_api_ 
dlist_create(miDLIST_TAG). If /ist is a null pointer, *tag is still deleted but no new list is installed. 
The main application of this function is to install a finalgather file name list in the options, with 


a call like 


miDlist *taglist = mi_api_dlist_create(miDLIST_TAG) ; 
mi_api_dlist_add(taglist, filename_string_tag); /*...*/ 
mi_api_taglist_reset (xoptions->finalgather_file, taglist) ; 
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4.2.3 Lights, Materials, Textures 


miLight *mi_api_light_begin( 
char *kname ) /* light name */ 


Begin the definition of a light with the specified name. A pointer to the light is returned; the caller 
may modify the structure. 


miBoolean mi_api_light_end(void) 
Complete the definition of a light after all parameters have been set. 


miMaterial *mi_api_material_begin( 
char *name ) /* material name */ 


Begin the definition of a material with the specified name. A pointer to the material is returned; 
the caller may modify the structure. 


miTag mi_api_material_end(void) 


Complete the definition of a material after all parameters have been set. If an error occurs, a 
null tag is returned; otherwise the tag of the new material element is returned. The type of the 
returned element is miSCENE_MATERIAL. 


miTag mi_api_texture_begin( 


char *xname, /* texture name */ 
int type, /* O=color, 1=scalar, 2=vector */ 
int flags) /* bitO=local, 1=filter, 2=writable */ 


Begin the definition of a texture with the specified name. In incremental mode, the tag of the 
existing texture to be changed is returned; otherwise a null tag is returned. The tag is useful 
mainly to determine whether the previous texture was an image or a shader, using the mi_db_type 
function. The type of the texture and a flags bitmap must also be specified. 


Bit 0 of the flags, if set, specifies that the texture is local. This is meaningful for image textures only, 
it specifies that each host on the network should read the image from its local file system instead 
of fetching the texture across the network. Memory-mapped textures are not flagged explicitly; 
they are recognized automatically at load time. Bit 1 of the flags, if set, specifies that the texture 
image is looked up using a filter. This flag is ignored for procedural (function) textures. 


Bit 1 of the flags, if set, enables pyramid filtering, an algorithm comparable to mip-map textures. 
mental ray will convert the texture to pyramid format, which takes about 30% more memory 
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but allows filtered lookups. This avoids texture aliasing, which is a problem for point-sampled 
non-filter textures that are far away so that each point sample hits widely spaced pixels in the 
texture. 


Bit 2°* of the flags, if set, specifies that the texture is writable. This flag should be set if the texture 
is attached to a lightmap shader that stores its data into the texture. 


This call is always the first stage of creating a texture and must be followed by one of the next 
three def calls, which complete the texture definition. 


void mi_api_texture_set_colorprofile( 
char *cprof_name) 


remembers the name of the color profile describing the color space of the texture. If a rendering 
profile has also been provided, then the texture will be transformed from this color profile to the 
rendering color profile while it is read. The routine has to be called before mi_api_texture_file_def 
is invoked. 


miTag mi_api_texture_file_def ( 
char *file) /*x file name to open */ 


The new texture is defined as a file texture, using the path file. The path must be valid on the local 
host and, if the texture is local, on all other hosts on the network. If an error occurs, a null tag 
is returned; otherwise the tag of the new texture element is returned. The type of the returned 
element is miSCENE_IMAGE. 


miTag mi_api_texture_function_def ( 
miTag function) /* function with args */ 


The new texture is defined as a procedural texture, using the texture shader function. Function 
tags are created when defining functions, and are returned by mi_api_function-_call_end. The local 
flag is ignored for procedural textures. If an error occurs, a null tag is returned; otherwise the tag 
of the new texture element is returned. The type of the returned element is miSCENE_FUNCTION. 


miBoolean mi_api_texture_array_def_begin( 


int xres, /* width in pixels */ 
int yres, /* height in pixels */ 
int zres) /* bytes/comp, 1 or 2 */ 


The final method of defining a texture is verbatim. It is equivalent to a file texture except that 
the pixel data is not read from a file on disk but is stored by the API caller using the texture 
copy calls below. This kind of texture cannot be flagged local. The texture resolution is set with 
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the xres and yres arguments. The number of bytes per component is set with the zres argument. 
The number of components per pixel is determined by the type argument of the preceding call to 
mi_api_texture_begin: 4 for color textures, 1 for scalar textures, and 2 for vector textures. Vector 
textures always assume 4 bytes per component (one float) regardless of whether zres is 1 or 2. 
If the verbatim texture is filtered, only the highest resolution is given with mi_api_texture_byte- 
copy; the lower resolutions of the pyramid are built automatically by mental ray. 


miBoolean mi_api_texture_byte_copy ( 
int len, /* number of bytes */ 
miUchar kbytes ) /* from the mi file */ 


After the texture was defined, the contents of the texture must be copied. A total of 
xres - yres - zres - nc bytes must be copied, with zres being 4 for vector textures and nc being 
the number of components (1 for 8 bits, 2 for 16 bits, or 4 for floating point’). The copy 
function can be called multiple times to collect the required number of bytes, the sum of all len 
arguments must be the total required number of bytes. The byte order is big-endian (MSB first) 
if zres is greater or equal to 1. Pixels are stored in pixel scanline order: first the bottom scanline 
is copied in RGBARGBA... order, then the next scanline, up to the top scanline. Scalar textures 
have only one component, vector texture pixels are stored U first, then V. 


miTag mi_api_texture_array_def_end (void) 


After all texture bytes have been copied, the texture must be completed with this call. If an error 
occurs, a null tag is returned; otherwise the tag of the new texture element is returned. The type 
of the returned element is miSCENE_IMAGE. 


miTag mi_api_texture_file_size( 


int xres, /* width in pixels */ 

int yres, /* height in pixels */ 

int zres, /* # of bytes per component */ 
int unused) /* reserved, must be 0 */ 


>-xTf the color texture is writable’*, mental ray needs to know the size (xres and yres) and the 
number of bytes per component (zres, 1 for 8 bits, 2 for 16 bits, and 4 for floating point). The 
unused argument is reserved for future extensions to data types other then RGBA, and must 
always be set to 0. 


miTag mi_api_texture_set_filter ( 
miScalar filter) /* value for filter scaling */ 


3-xThis function sets the filter constant of the texture. It must be set with this function instead of 
writing the filter value into the texture structure directly, as was done in mental ray 2.1, because 
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the texture is created on demand. This function only works if the texture lives in memory. If it 
is a memory-mapped texture created with imf_copy using the .format, the filter value must be 
specified when the map file is created, using imf_copy’s -f option. 


void mi_api_texture_end() 
ends the definition of a texture. 


4.2.4 User Data 


Sometimes large amounts of opaque data must be entered into the scene that cannot be efficiently 
handled with shader parameters. For example, shaders may need large amounts of particle data. 
For this purpose, user data blocks can be defined. A user data block consists of a header describing 
the data block, and the data itself. User data blocks are named. 


miUserdata *mi_api_data_begin( 


char *xname, /* name of user data block */ 
int type, /* O=literal, 1=file, 2=declared */ 
void *parm) /* type O:size, 1:file, 2:decl */ 


Begin the definition of a user data block named name. Its contents can be defined in three different 
ways: if type is 0, the data must be copied verbatim with mi_api_data_copy (see below); if type is 1, 
the data is read from a file; and if type is 2, the data is defined similar to regular shader parameters. 
This last mode is useful if the data block itself is not large but shared among a large number of 
shaders or other elements. In mode 0, parm is an integer specifying the number of bytes to be 
stored. In mode 1, parm is an allocated string that specifies the file name to load from. In mode 
3, parm is the tag of a function that the parameters will be taken from (this works exactly like the 
params argument of the mi_api_instance_end function except that the declaration can, but doesn’t 
have to, be of type miFUNCTION_DATA). This function returns a pointer to the new user data block, 
which lets the caller set up the miUserdata header. 


miTag mi_api_data_end(void) 
Complete the definition of the user data block, and return its tag. 


miTag mi_api_data_append ( 
miTag front, /* list to append to */ 
miTag back) /* list to append */ 


Append the back user data block list to the front user data tag list, and return the first tag of the 
concatenated list. Either or both lists may be empty (front and/or back is a null tag). User data 
block concatenation works the same way as shader list concatenation. 
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miBoolean mi_api_data_byte_copy ( 
int len, /* number of bytes */ 
miUchar *bytes) /* bytes from the mi file */ 


Append the given number of bytes to the user data block. This must be called between mi_api_ 
data_begin and mi_api_data_end if the type of the user data block is 0. It may be called zero or 
more times, and the sum of all /en arguments may not exceed the user data block size specified 
in the begin call. If this function may not be called for type 1 or 2 blocks, it overwrites data from 
the file or parameters. 


miTag mi_api_data_lookup( 
char *name ) /* data block name to look up */ 


Look up the user data block with the given name, and returns its tag. If the database element with 
that name is not a user data block, or if the name is unknown, an error is printed and a null tag is 
returned. 


4.2.5 Light Profiles>: 


Light profiles such as IES or Eulumdat are files provided by physical lamp vendors to specify 
the light emission characteristics of their products. The profile files can be read and preprocessed 
by mental ray, and access and measurement functions are supplied to shaders. The following API 
calls implement the lightprofile...end lightprofile blocks in .mi scene files, which attach 
a name to a profile that can be passed to shaders as an argument of type lightprofile. 


miLight_profile *mi_api_lightprofile_begin( 
char *kname ) /* name of light profile */ 


Begin the definition of a light profile named name, and return a pointer to the new light profile. 


The caller should set the following fields: 


e filename: the name of the profile file, as a tag of type miSCENE_STRING. 
e format: either miLP_STD_IES or miLP_STD_EULUMDAT. 

e base: always miLP_BASIS_HERMITE. 

e quality: the hermite degree, 1 or 3, 1 is default. 


e n_vert_angles, n_horz_angles: the number of measurement points interpolated from the 
mesh in the light profile file. If either is 0 (the default), mental ray will use the resolution in 
the profile file. 


e flags: if O (the default), use the sample order defined in the profile. If 1, force horizontal 
angles to grow clockwise when observed from zenith. If 2, force horizontal angles to grow 
counterclockwise when observed from zenith. 


468 4 Geometry Shaders 


After all fields are defined, call m1_api_lightprofile_end. 
miTag mi_api_lightprofile_end (void) 
Completes the definition of the light profile. 


miTag mi_api_lightprofile_lookup( 
char *kname ) /* symbolic profile name */ 


Returns the tag associated with the symbolic name of a light profile. This function is not required; 
it may be useful when defining shader parameter values for parameters of type lightprofile. 


4.2.6 Color Profiles** 


The following API calls implement the colorprofile ... end colorprofile blocks in .mi 
scene files, which attach a name to a profile. 


miColor_profile *mi_api_colorprofile_begin( 
char «name ) /* name of color profile */ 


>-*Begin the definition of a color profile named name, and return a pointer to the new color profile. 
The caller should set the following fields: space describes the color space associated with the 
color profile. Valid color spaces are miCPROF_RGB, miCPROF_NTSC, miCPROF_HDTV, miCPROF_SHARP, 
miCPROF_CIEXYZ, miCPROF_CIEXYY, miCPROF_LINERGB, miCPROF_BOXRGB, miCPROF_CUSTOM. For 
custom color spaces the bit defined by miCPROF_CID_NOT_ENOUGH needs also to be set 
in the space field. It is recommended to use the routine mz_api_colorprofile_space to set the space 


field. 


The caller may set the following fields: white_adapt should be set to true if a white adaption is 
requested when transforming to other color spaces. If this value is false, then the white point 
intrinsic to the color space is used. white contains the CIE XYZ coordinates of the white point 
assigned to the color space. Other fields should only be set through the provided interface routines 
below. 


miUint1 mi_api_colorprofile_space( 
char *kname ) /* name of color space */ 


*4may be used to set the space field of the current color profile. The routine parses the name 


string describing the name of a color space and returns the value to be used for the space field. 
The routine will release the memory associated with its parameter. Valid argument strings are 
“rgb”, “hdtv”, “ntsc”, “ciexyz”, “ciexyy”, “linergb”, “boxrgb”, and “sharp”. There is no string 
for sRGB, since this color space differs from the HDTV standard only by the gamma correction. 
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void mi_api_colorprofile_gamma ( 


miScalar gamma , /* gamma corr. exponent */ 
miScalar offset, /* below gamma corr. is linear */ 
miBoolean force) /* allow values < 1 */ 


*-4is used to assign a gamma correction to the current color profile. The gamma correction mapping 


associated with color spaces like HDTV or sRGB are not just exponentiation, since electronic 
circuits cannot properly deal with infinite slopes at the origin. Hence, gamma corrections are 
often assumed to be linear below a certain threshold offset value. This routine takes such models 
into account and will set all gamma parameters in the color profile. If the force argument is set 
to true, then values of the gammma exponent below 1.0 will be directly used, else the reciprocal 
value is used for exponents below 1.0. 


void mi_api_colorprofile_white ( 


miColor *white, /* return white point */ 
int temperature, /* color temperature */ 
miScalar intensity) /* intensity of white */ 


>4will caculate the CIE XYZ coordinates of a white point given by the color temperature 
associated with CIE D illuminant. Valid temperatures are between 4000 and 25000 Kelvin. A 
value of 6500 Kelvin corresponds to the color temperature of an average overcast sky (D65 
illuminant). The provided temperature is used to calculate an associated color. This color may be 
scaled to the provided intensity. 


miBoolean mi_api_colorprofile_custom( 
miColor_profile *cprof, /* color profile */ 
miMatrix m) /* custom transform */ 


>4Tf the space field is set for a custum color profile, then this routine may be called to set the color 
space transformation matrix and its inverse for the passed in color profile. The routine will only 
use the upper 3 by 3 sub-matrix and assume that this matrix describes the transform from CIE 
XYZ space to the custom color space. After all fields are defined, call mz_api_colorprofile_end. 


miTag mi_api_colorprofile_end() 
Completes the definition of a color profile. 


4.2.7. Instances and Instance Groups 


Instances and instance groups are used to construct the scene DAG (directed acyclic graph). 
Instance groups are unordered lists of one or more instances. Instances are nodes of the DAG, 
they reference an item to be placed into the DAG together with a space transformation, optional 
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inheritance parameters, and various flags. Elements that can be referenced by instances are 
geometric objects, cameras, lights, and instance groups. If more than one instance references 
the same item, this is called multiple instancing. 


miInstance *mi_api_instance_begin( 
char *«name ) /* instance name */ 


Begin the definition of an instance with the given name. In incremental mode, a pointer to the 
existing instance is returned; otherwise a pointer to a temporary instance is returned. It is not 
necessary to store the various flags and IDs in the instance transformation, this is done during 
preprocessing. 


miTag mi_api_instance_end( 


char *xitem, /* item to instance */ 
miTag function, /* geometry shader */ 
miTag params ) /* transformation func */ 


Complete the definition of the instance. If the instanced item is not a geometry shader, the item to 
be instanced is given by item and function must be a null tag. If the instanced item is a geometry 
shader, the function list is passed in function and item must be a null pointer. It is an error if both 
item and function are requested to be instantiated. Incremental changes from regular to geometry 
shader instances and vice versa are possible. 


The params tag is either the null tag (no inheritance parameters), the numerical value -1 (leave 
parameters unchanged during an incremental change), or the tag of a function containing 
inheritance parameters. Only the parameters are used, the function is ignored. The function 
should be deleted after being passed to mi_api_instance_end. 


If an error occurs, a null tag is returned; otherwise the tag of the new instance element is returned. 
The type of the returned element is miSCENE_INSTANCE. 


miBoolean mi_api_instgroup_begin( 
char *kname ) /* group name */ 


Begin the definition of an instance group with the given name. The list of elements is not cleared 
even if incremental mode is disabled. 


miBoolean mi_api_instgroup_clear (void) 


After the instance group definition was begun, all its instances references can be cleared with this 
call, as if mi_api_instgroup-_delitem had been called for every one of them. 
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miBoolean mi_api_instgroup_additem( 
char «name ) /* instance name */ 


After the instance group definition was begun, instances can be added to it. The order of the 
instances being added is irrelevant. Only instances can be added, never elements such as geometric 
objects directly. 


miBoolean mi_api_instgroup_delitem( 
char *kname ) /* instance name */ 


After the instance group definition was begun, instances can be deleted from it. 
miTag mi_api_instgroup_end (void) 


After all instances have been added to the instance group, this call completes the creation of the 
instance group. If an error occurs, a null tag is returned; otherwise the tag of the new instance 
group element is returned. The type of the returned element is miSCENE_GROUP. 


4.2.8 Geometric Objects 


Geometric objects can be divided into polygonal, free-form surface, and space curve objects. Each 
object contains one or more object groups that group geometry. Object groups are maintained 
for backwards compatibility with the .mil language; newer designs should use multiple objects 
rather than a single object with multiple object groups. Object groups are unrelated to instance 
groups as described above. 


4.2.8.1 Objects 


mi0bject *mi_api_object_begin( 
char *name ) /* object name */ 


Begin the definition of an object with the given name. If the name parameter is zero, the object is 
not registered in the symbol tables, so it cannot be referenced by name. In this case the tag returned 
by m1_apt_object_end must be used for referencing the object. All geometrical information is 
deleted regardless of incremental mode. This is the first call of the object definition sequence. 
After the object begin, first bases are defined if the object contains free-form surfaces. Next, the 
object group or groups must be defined. The returned mi0bject pointer can be used to write the 
visible and other flags into the object. Note that since the final size of the object is not known 
at this point, the returned pointer points to a temporary structure that does not contain geometry 


and that will be deleted by mi_api_object_end. 
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miBoolean *mi_api_object_matrix( 
miMatrix transform) 


This function is for backwards compatibility with the .mil syntax only. It stores the object’s 
texture transformation matrix. It should not be used. 


miBoolean mi_api_object_group_begin ( 
double merge) /* merge epsilon */ 


The next step after the begin call is beginning an object group. The merge argument is obsolete 
and must be set to 0.0. 


miBoolean mi_api_object_group_connection ( 


char *surfnamel, /* first surface */ 
char *curvenamei1, /* first curve */ 
miGeoRange *rangel, /* of first curve */ 
char *surfname?2, /* second surface */ 
char *curvename2, /* second curve */ 
miGeoRange *krange2) /* of second curve */ 


After all surfaces in the free-form object have been defined, just before mi_api_object_group_end 
is called, this function can be used to establish connections between surfaces. Connections can 
only be defined along the trimming curves on the surfaces, which must exist. Untrimmed surfaces 
cannot be connected, but a trivial trim curve that follows the parameter boundaries such that no 
part is actually trimmed off is simple to create. A parameter range must be specified for both 
curves. 


miBoolean mi_api_object_group_end (void) 


After all geometry in the object group has been defined, this function completes the object group 
definition. Another group can be begun after ending the current one. 


miBoolean mi_api_object_file( 
char *file) 


°*Instead of defining geometry with mi_api_object_group_begin and mi_api_object_group_end, 
define the object as a placeholder object. This requires that a bounding box and, if applicable, a 
motion bounding box and a max displacement are defined in the object. mental ray 3.0 will read 
the object from the specified .mi scene file file when it needs the geometry. The file must define 
the exact same object, including the name and all flags and options, except that it must contain 
the actual geometry bracketed with group and end group. Note that placeholder objects may 
only contain a single object group...end group block. 
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typedef miBoolean (*miApi_object_callback) (miTag, void *); 


miBoolean mi_api_object_callback( 
miApi_object_callback cb, 
void *data) 


>-*This is an alternative to mi_api_object_file. It also creates a placeholder object, but instead of 
reading a file, mental ray 3.x will call the callback cb. The callback receives the opaque data pointer 
data (intended for passing C++ this pointers), and the tag of the object to define. The callback 
must then look up the name (mi_api_tag_lookup), enter incremental mode (mi_api_incremental), 
and redefine the object from scratch, except this time with geometry. It is important that the object 
has only a single object group because multi-group objects are supported only for backwards 
compatibility with mental ray 1.x and are automatically converted to instance groups containing 
separate objects, and mental ray does not support placeholder instance groups because that would 
defeat the purpose. 


In mental ray up to 3.2, the callback must specify the same flags, the same label, and the same 
or smaller bounding box, motion bounding box, maxdisplace, and ray offset values. It may add 
a userdata tag by looking up an existing userdata block, but not create a new one (it would be 
leaked because nobody is going to delete it later). mental ray 3.3 and later copy the flags and label 
automatically, so the callback no longer has control over them. if the callback does not set the 
bounding boxes, maxdisplace, or ray offset, mental ray will copy them automatically. Note that 
the callback may provide smaller bounding boxes and maxdisplace than originally specified, if it 
has better knowledge about the object and can provide tighter bounding boxes, but it may never 
enlarge them. 


This is the recommended method for defining large objects with geometry shaders because no 
memory or time is spent until the object is actually needed, and if memory runs out (see mi_job_ 
memory_limit), mental ray can evict the object from the cache to make room for more important 
data. It could not evict normal geometry shader-generated objects because they cannot be rebuilt 
on demand. Also, mental ray can run different object callbacks in parallel if necessary. 


miTag mi_api_object_end(void) 


Complete the finished object. This is the last call of the object definition sequence. If an error 
occurs, a null tag is returned; otherwise the tag of the new object or group element is returned. 
API decides whether to create and return an object or an instance group element based on the 
object complexity: if it has multiple object groups or connections, an instance group is created 
that has the merge group flag set, and references one or more instances, each of which references 
an object element containing a single object group. If there is only one object group and no 
connections, the object is created and returned directly without creating intermediate instances 
or connections. This decision is transparent to the caller; the tessellator accepts instance groups 
in this case as well as objects. The type of the returned element is either miSCENE_OBJECT or 
miSCENE_GROUP. 
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4.2.8.2. Bases 


Objects containing free-form surfaces must contain at least one basis. A basis defines the curve 
type or one of the two surface parameter axis types (e.g., NURBS or Bézier), a rational flag, and 
the degree. All surfaces in all object groups of an object share the same basis list in the object, and 
reference bases by name. 


miBoolean mi_api_basis_list_clear (void) 


Delete all bases in the current object basis list. This function is largely obsolete because it 1s 
implicitly called when beginning and ending objects. 


miBoolean mi_api_basis_add( 


char *name , /* name of basis */ 
miBoolean rational, /* rational surface? */ 
enum miBasis_type type, /* basis type */ 
miUshort degree, /* degree of basis */ 
miUshort stepsize, /* opt. step size */ 
miDlist xmatrix) /* opt. basis matrix */ 


Append a basis to the basis list of the current object. The basis name, a rational flag, the basis type, 
and the degree must be defined. The matrix stepsize and the basis matrix must be defined only 
for the basis matrix type. The matrix is passed as a dlist (dynamic list, see above) because its size 
depends on the degree of the basis; (degree + 1)? floating-point numbers of type miGeoScalar 
are expected. 


miGeoIndex mi_api_basis_lookup( 


char *name , /* basis to look up */ 
miBoolean *rational, /* rational flag */ 
miUshort *degree) /* returned degree */ 


This function allows basis lookups by basis name. The sequential number of the basis in the 
object’s basis list is returned, as well as the rational flag and the degree if the second and third 
arguments are non-null pointers. This function is not essential for scene definition. 


4.2.8.3 Polygonal Geometry 


An object group can contain either polygonal or free-form surface geometry. Polygonal geometry 
requires the definition of three blocks of data: vectors, vertices, and polygons. Optionally, an 
approximation may be given which is used by the tessellator for displacement-mapped polygons. 
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miBoolean mi_api_geovector_xyz_add( 
miGeoVector xnewvec) /* vector to append */ 


miBoolean mi_api_vector_xyz_add( 
miVector *xnewvec) /* vector to append */ 


After beginning the object group that should contain polygonal geometry, one call to this function 
for every XYZ vector to be used must be done. Vectors will be referenced by sequential number, 
beginning with 0 in every object group, to be used as points in space, normals, motion vectors, 
and various other purposes. There are restrictions of vector sharing; for example, a vector cannot 
be used as a point in space and a normal at the same time. Also, vectors should be listed in a 
certain order (points in space first, then normals, and so on) for maximum efficiency. Any other 
order will be re-sorted automatically. 


There are two versions of this call. The first accepts double-precision vectors and the second 
accepts single-precision vectors. Both store the vectors in double precision. If the vector is 
available in double precision, always use mi_api_geovector_xyz_add to avoid precision loss. Both 
versions can be mixed, they are identical except for the argument type. 


miBoolean mi_api_vector_lookup( 
miGeoVector *pOS, /* vertex position */ 
int idx) /* index of vector */ 


This function looks up a vector in the current object by index, and returns its value. This function 
is not essential for scene definition. 


miBoolean mi_api_vertex_add( 
int p) /* point in space */ 


miBoolean mi_api_vertex_normal_add( 
int n) /* normal vector */ 


miBoolean mi_api_vertex_deriv_add( 
int i. /* dPdu derivative */ 


int v) /* dPdv derivative */ 


miBoolean mi_api_vertex_deriv2_add( 


int u, /* d2Pdu2 derivative */ 
int V, /* d2Pdv2 derivative */ 
int uv) /* d2Pduv derivative */ 


miBoolean mi_api_vertex_tex_add( 
int : /* texture parameter vector */ 
int x. /* X basis vec or -1 */ 
int y) /* Y baste vecor -1-*/ 
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miBoolean mi_api_vertex_motion_add( 
int m) /* motion vector */ 


miBoolean mi_api_vertex_user_add( 
int u) /* user vector */ 


After all vectors have been defined, vertices must be defined. Vertices must contain a point in 
space, defined with mi_api_vertex_add, optionally followed by a normal, first and second surface 
derivatives, one or more texture vectors with optional bump basis vectors, a motion vector, and 
one or more user vectors. After the initial point in space, the order of the other calls is fixed. 
Vectors are referenced by sequential number in the object group, with 0 being the first vector. A 
vector index —1 means “none,” which is useful for defining texture vectors without bump basis 
vectors. Either no or two bump basis vector indices must be given. All add functions until the 
next call to mi_api_vertex_add or the end of the vertex list append to the current vertex. The next 
mi_api_vertex_add begins the next vertex. 


miBoolean mi_api_vertex_lookup( 
miGeoVector *pos, /* vertex position */ 
int idx) /* index of vertex */ 


This functions looks up the point in space of the vertex specified by the index idx. Vertices, like 
vectors, are sequentially beginning with 0 in every object group. This function is not essential for 
scene definition. 


miBoolean mi_api_poly_begin( 
int type, /* O=concave, 1=convex */ 
char *material) /* material name */ 


miBoolean mi_api_poly_begin_tag( 
int type, /* O=concave, 1=convex */ 
miTag material) /* material tag */ 


After all vectors and vertices have been defined, polygons are defined. Each polygon requires a 
begin call followed by at least three index add calls followed by an end call. Optionally, holes may 
be defined. At this time, type must be either 0 (concave or unknown) or 1 (convex). Specifying 
type 1 improves performance because the tessellator does not need to test the convexity of the 
polygon. The first polygon in an object group must always specify a material by either a name or 
a tag, therefore the two begin functions are provided. For all following polygons, a null pointer 
or a null tag may be passed to specify “same material as before in the same object group.” This 
improves API performance. In the case of tagged objects, the material pointer or tag must be 
null; the label is passed as an extra index (using mi_api_poly_index_add) before the regular vertex 
indices. 


miBoolean mi_api_poly_index_add( 
int idx) /* new index to append */ 
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After the polygon begin call, at least three vertices must be specified by index. The first vertex in 
the current object group has index 0. The order is significant; polygon vertices must be defined 
in counter-clockwise order. Polygons (and their holes) should be planar. Small deviations are 
handled gracefully but very large deviations may lead to unpredictable behavior. This function is 
also used to store the polygon label directly after mi_api_poly_begin if the object is tagged. 


miBoolean mi_api_poly_hole_add(void) 


After the boundary loop of the polygon has been specified using index add calls, this call may be 
used to indicate the end of the current loop and the beginning of a hole loop. Hole loops, like 
boundary loops, consist of a sequence of at least three index add calls. No two loops may intersect, 
and a hole loop must be fully contained in the boundary loop in the plane of the polygon. 


miBoolean mi_api_poly_end(void) 


After all boundary and optional hole loops have been added, the polygon must be completed 
with this call. After the end call, a new polygon may be begun. 


miBoolean mi_api_poly_approx( 
miApprox *approx) /* approx technique */ 


After the last polygon an approximation statement may be specified. It is used by the tessellator for 
displacement-mapped polygons only. Displacement mapping is a feature of the material assigned 
to polygons. 


4.2.8.4 Free-Form Surface Geometry 


Object groups containing free-form surfaces also consist of three sections: the vector list, the 
vertex list (more accurately called the control point list), and the curve and surface lists. The 
vector list is defined using one call to mi_api_vector_xyz_add for every vector. All vectors have 
three components X, Y, Z; weights for rational curves and surfaces are specified as part of the 
vertex references later. 


The vertex list is defined with calls to mi_api_vertex_add, exactly like in the polygonal case, except 
that all normals, textures, and other optional vertex information except motion vectors is ignored 
and should not be specified. Surfaces always compute their own normals, and there are special 
constructs for textures and bump maps. 


The curve and surface list uses the vertices defined in the first section as control points. Curves 
can be used as trimming curves, hole curves, and special curves. Vertices can also be used as special 
points on surfaces. Special points and special curves are always included in the tessellated surface. 
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miBoolean mi_api_surface_begin( 
char *name, /* surface name */ 
char *xmtlname) /* material name */ 


Begin the definition of a surface with the given name. The name is valid only inside the object 
group and is used for connections and approximations. The given material is assigned to the 
surface. The name may not be a null pointer. 


miBoolean mi_api_surface_begin_tag( 
Chay xname , /* surface name */ 
miTag mtltag) /* material name */ 


This function is similar to mi_api_surface_begin, but instead of a name a material tag must be 
specified. This tag may not be a null tag. 


miBoolean mi_api_surface_params ( 


int dimen, /* miU or muV */ 

char *basis_name, /* basis for U or V */ 
miGeoScalar range_min, /* minimum range */ 
miGeoScalar range_max, /* maximum range */ 
miDlist *params, /* params for U or V */ 
miBoolean rational) /* rational flag */ 


A surface has two parameter directions, U and V. After the surface begin call, both must be 
defined with this call, once with dimen = miU and once with dimen = miV. Both times, the basis 
name as defined at the beginning of the object definition must be given, as well as the parameter 
range, the surface parameter list, and the rational flag. The rational flag can either be set here 
or in the basis; the latter is recommended. The rational flag can be specified here for backwards 
compatibility with the .mil language. 


The parameter list is a dlist (dynamic list, see above) containing the parameter vector. The length of 
this vector depends on the basis; refer to the .mi2 language specification in the mental ray manual 
for the exact numbers. The type of the dlist is miDLIST_GEOSCALAR, containing floating-point 
numbers of type miGeoScalar. 


miBoolean mi_api_vertex_ref_add( 
int ref, /* vertex reference */ 
double w) /* homogeneous coordinate */ 


After both surface parameter vectors have been specified, the control points must be listed. The 
number of control points depends on both bases and the length of their parameter vectors; again 
refer to the mental ray manual for details. For every control point one call to mi_api_vertex_ref_ 
add is required. If both bases are non-rational, it is sufficient to specify a vertex index ref. As 
with polygons, 0 selects the first vertex in the current object group. For rational bases, a weight 
w must be given for every control point reference. 
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miBoolean mi_api_surface_curveseg( 


miBoolean newloop, /* new loop? */ 

enum miCurve_type type, /* type of curve */ 
char *xname , /* existing curve */ 
miGeoRange *range ) /* curve range */ 


After the surface parameters have been defined, this call can be used to attach curves to the 
surface. The curve must have been defined in the same object group (see below) and is referenced 
by name. The type of the curve is one of miCURVE_TRIM, miCURVE_HOLE, and miCURVE_SPECIAL. 
The parameter range specifies the piece of the curve to be used. Multiple curves or pieces of 
curves can be concatenated to form the final loop; curves specified by consecutive mi_api_surface- 
curveseg are concatenated to a single loop by setting newloop to miTRUE for the first call and to 
miFALSE for all following curves to be appended. 


miBoolean mi_api_surface_specpnt ( 
int uv_index, /* 2D point reference */ 
int v_index) /* optional 3D point */ 


Attach a special point to a surface. A vertex index uv_index must be given that contains the 
coordinate in the surface’s UV space. The tessellated surface will contain a triangle vertex at that 
UV coordinate. If v_index is not —1, the special point is assigned the XYZ coordinate contained 
in the indexed vertex. 


miBoolean mi_api_surface_texture_begin( 


miBoolean is_volume, 
miBoolean is_bump, 

char *ubasis_name, 
miDlist *uparams , 
miBoolean u_rational, 
char *vbasis_name, 
miDlist *vparams, 
miBoolean v_rational) 


This call attaches a texture surface to the most recently defined surface. A texture surface is a 
simplified type of surface that causes texture vectors to appear in the vertices of the triangles 
that result from tessellation. Whenever the tessellator creates a triangle vertex at a certain UV 
coordinate of the main surface, it looks up this UV coordinate in the texture surface and computes 
the location of the texture surface at that point, and stores that as texture vector. If zs_volume is 
miFALSE, wrap compensation is applied before storing the texture vector; this ensures that texture 
lookups near the surface seam do not “rewind.” Generally it should be miFALSE for 2D textures 
and miTRUE for 3D (volume) textures. If is_bump is miTRUE, a pair of basis vectors is created in 
the tessellated surface instead of a texture vector. The bases and parameters in both the U and 
V directions are specified in the same call; they must use the same parameter ranges as the base 
surface. 
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Note that whenever the texture on a surface looks strangely shifted, or if texture coordinates are 
too large by a constant of 1, the reason is usually that zs_volume had not been set to miTRUE on a 
3D texture. 


miBoolean mi_api_surface_derivative( 
int degree) /* 1=1st, 2=2nd deriv */ 


Specify that during tessellation, first or second derivatives should be computed and stored with 
the vertices of the tessellated surface that was most recently begun with mi_api_surface_begin. If 
both first and second derivatives should be stored, this function must be called twice. 


miBoolean mi_api_surface_end(void) 


After the surface, both of its parameter directions, all its texture surfaces and its derivatives have 
been specified, this call must be used to complete the surface definition. After this call, the next 
surface can be started by repeating the sequence beginning with mi_api_surface_begin. 


miBoolean mi_api_surface_approx ( 
char xname, /* name of surface */ 
miApprox *approx) /* approx technique */ 


After the definition of a surface is complete, an approximation can be attached to it. The default 
is parametric approximation. This call can be used to change the default to regular parametric, 
curvature-dependent or spatial approximations. This call must be used before the object group 
ends because at that point the surface names go out of scope. 


miBoolean mi_api_surface_approx_displace( 
char xname, /* name of surface */ 
miApprox *xapprox) /* approx technique */ 


In addition to mi_api_surface_approx, which control the approximation of the base surface, this 
function stores an approximation for the displaced surface. The default is parametric. This is 
often useful to provide a high-resolution parametric approximation for the base surface to catch 
small displacement map features, and a curvature dependent tessellation for the displaced surface 
to properly approximate the curvature introduced by the displacement. For mental ray 3.1, fine 
approximation allows resolving extremely detailed displacement maps efficiently. 


miBoolean mi_api_surface_approx_trim( 
char xname, /* name of surface */ 
miApprox *kapprox) /* approx technique */ 


This function assigns an approximation to the trimming, hole, and special curves attached to the 
named surface, just like the previous function assigns an approximation to the surface itself. 
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4.2.8.5 Curves 


Curves can be used as trimming curves, hole curves, and special curves as described in the free- 
form surface section above. In addition, curves can be used in space curves to represent curve 
objects. 


This section lists the API functions to create curves. This can be done inside any object group, 
after the vectors and vertices are defined, in any place where a surface definition would be legal. 
Like surface names, curve names are in object group scope and can only be referenced in the 
object group they are defined in. 


miBoolean mi_api_curve_begin( 


char *xname, /* name of the curve */ 
char *basis, /* name of the basis */ 
miBoolean rational) 


Create a new curve with the given name, using the specified basis. Like surfaces, a rational flag 
can be set for backwards compatibility reasons. The recommended method is setting the rational 
flag in the basis. Curves and surfaces can share the same bases. 


miBoolean mi_api_curve_specpnt ( 
int t_index, /* 1D point reference */ 
int v_index) 


Attach a special point to a curve at the parameter point v_index of the curve. v_index references 
the vertex to use; only the X value is used. 


miBoolean mi_api_curve_end( 
miDlist *d1p) /* parameter list */ 


Complete the definition of the curve, and pass the parameter vector. The type of the dlist is either 
miScalar for the non-rational case or miVref for the rational case. 


miBoolean mi_api_curve_approx ( 
char *xname , /* name of curve */ 
miApprox *approx) /* approx technique */ 


This function assigns an approximation to the curve. Alternatively, an approximation can be 
assigned to all curves used in a surface at once using mi_api_surface_approx_trim, which overrides 
the approximation set with mi_api_curve_approx. 
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4.2.8.6 Space Curves 


This section lists the API functions to create space curves. Space curve objects are primarily useful 
in geometry shaders, they are not used for rendering. Geometry shaders can build renderable 
surfaces with space curve objects or use them for dynamic trimming operations on surfaces. The 
definition can be done inside any object group, after the vectors and vertices are specified. Like 
curve or surface names, space curve names are in object group scope and can only be referenced 
in the object group they are defined in. 


miBoolean mi_api_spacecurve_begin( 
char «name ) /* space curve */ 


Create a new space curve with the given name. 


miBoolean mi_api_spacecurve_curveseg ( 


miBoolean newloop, /* is this a new loop */ 
char *name, /* curve name */ 
miGeoRange *xrange ) /* range of the curve */ 


This call can be used to attach curve segments to the space curve. The curve must have been 
defined in the same object group (see below) and is referenced by name. The parameter range 
specifies the piece of the curve to be used. Multiple curves or pieces of curves can be concatenated 
to form the final space curve; curves specified by consecutive mi_api_spacecurve_curveseg are 
concatenated to a single curve by setting wewloop to miTRUE for the first call and to miFALSE for 
all following curves to be appended. 


miBoolean mi_api_spacecurve_approx ( 
char xname , /* name of surface */ 
miApprox kapprox) /* approx technique */ 


After the definition of a space curve is complete, an approximation can be attached to it. The 
default is parametric approximation. This call can be used to change the default to regular 
parametric, curvature-dependent or spatial approximations. This call must be used before the 
object group ends because at that point the space curve names go out of scope. 


miBoolean mi_api_spacecurve_end (void) 


This function must be called to finalize the definition of a space curve. After this call, the next 
space curve can be started by repeating the sequence beginning with mi_api_spacecurve_begin. 
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4.2.8.7. Hair?! 


Hair geometry shares the same object begin and end calls with all other geometry types, but the 
actual geometry uses special mi_api_hair—* calls instead of mi_api_object_group_begin and m1i_ap1- 
object_group_end. The sequence is 


mi_api_hair_begin 


mi_api_hair_info (zero or more calls) 
mi_api_hair_scalars_begin 
mi_api_hair_scalars_end (followed by array write) 
mi_api_hair_hairs_begin 

mi_api_hair_hairs_add (once per hair plus 1) 


mi_api_hair_hairs_end 
mi_api_hair_end 


The mi_api_hair_info calls are optional; they describe the information attached to hairs and vertices 
(for details see page 150). 


miHair_list *mi_api_hair_begin(void) 


Begin a hair block in an object. The returned hair list may be used to specify the global fields 
material, radius, degree, approx, space_-max_size, and space_-max_depth. 


miBoolean mi_api_hair_info( 


int where, /* O=per hair, 1=per vertex */ 
char what, /* n=norm,m=mot ,t=tex,u=user ,r=radius*/ 
int num) /* how many? */ 


Specify that each hair (if where == 0) or each vertex (if where == 1) has the specified number 
of normal scalars (what == ’n’, num must be 0 or 3), number of motion scalars (what == ’m’, 
num must be 0 ora multiple of 3), number of texture scalars (what == ’t’), number of user scalars 
(what ==’u’), or whether it has a radius (what == ’r’, either 0 or 1). If there are vertex normals, 
vertex motion vectors, or a vertex radius, the hair normals, hair motion vectors, or hair radius, 


respectively, are ignored. 


miScalar *mi_api_hair_scalars_begin( 
int num ) /* expected number of scalars */ 


After the hair info, the scalar list follows in the hair object definition. The num argument specifies 
the number of scalars in the hair object. This function returns a scalar array with room for num 
scalars, which the caller must fill. See page 535 for the scalar layout. There is no add-scalar 
function for performance reasons. 
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miBoolean mi_api_hair_scalars_end( 
int num) /* received number of scalars */ 


After all scalars have been defined, this function must be called. It performs some consistency 


checks. 


miGeoIndex *mi_api_hair_hairs_begin( 
int num) /* expected number of hairs + 1 */ 


After the scalar definition, the hair indices must be defined with this function. The number num 
is the number of indices that follow, which is the number of hairs plus 1. Again, see page 535. A 
pointer to an index array with num indices is returned, which the caller must fill by calling mz_ 
api_hair_hairs_add repeatedly, or manually. 


miBoolean mi_api_hair_hairs_add( 
int si) /* index into scalar list */ 


Add a hair index sz. This ends the definition of the previous hair, if any, and begins a new hair 
(unless this is the last index). Each hair needs a fixed number of scalars: the number required by 
the hair info (data shared by all vertices of the hair), followed by one or more vertex info blocks 
(data separate for each hair), as defined with mi_api_hair_info. Note that there need to be as many 
calls to this function as have been specified by the mum argument of the mi_api_hair_hairs_add 
call, which is one more than the number of hairs (to terminate the last hair). The first hair index 
is normally 0, and the last hair index normally equals the number of scalars num passed to mi-_ 
api_hair_scalars_begin. 


miBoolean mi_api_hair_hairs_end(void) 


This function concludes the definition of indices. The next call is probably mi_api_hair_end. 


void mi_api_hair_end (void) 


Finish the definition of the hair geometry. The next call is probably mi_api_object_end. 


4.2.8.8 Subdivision Surfaces 


Object groups containing subdivision surfaces also consist of three sections: the vector list, the 
vertex list, and the subdivision surface list. As before, the vector list is defined using one call to 
mi_api_vector_xyz_add for every vector, and the vertex list is defined with calls to mi_api_vertex- 
add like in the polygon case. The subdivision surface list uses the vertices for both position and 
detail vertices. Subdivision surface vertices can have flags attached, they can be added by calling: 
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typedef enum { 
miAPI_V_SMOOTH=0, 
miAPI_V_CORNER, 
miAPI_V_CONIC, 
miAPI_V_CUSP, 
miAPI_V_DART 

} miApi_vertexflags; 


miBoolean mi_api_vertex_flags_add( 
miApi_vertexflags flags, 
miScalar value) 


This function adds a sharpness feature to the current vertex beginning with a specified level. 
It should be called only once for each vertex, and may be called for individual vertices. If not 
called for a vertex, default flags are used (miAPI_V SMOOTH), which will lead to smooth vertex 
processing. value specifies the sharpness for conic and cusp vertices. For corner vertices zero 
sharpness should be passed. It is redundant to mark a vertex smooth with this call. 


The call order for subdivision surface construction is 


mi_api_subdivsurf_begin 


mi_api_subdivsurf_index (n times) 
mi_api_subdivsurf_baseface 
[mi_api_subdivsurf_crease_edge (optional) 
mi_api_subdivsurf_crease] (optional) 
mi_api_subdivsurf_trim (optional) 
mi_api_subdivsurf_mtl (optional) 
[mi_api_subdivsurf_push (block optional) 
mi_api_subdivsurf_subdivide 
mi_api_subdivsurf_mtl (optional) 
[mi_api_subdivsurf_index (up to 6/9 times) 
mi_api_subdivsurf_detail] (optional) 
[mi_api_subdivsurf_crease_edge (optional) 
mi_api_subdivsurf_crease] (optional) 
mi_api_subdivsurf_trim (optional) 
[mi_api_subdivsurf_push (optional) 


mi_api_subdivsurf_subdivide 


mi_api_subdivsurf_pop] 
mi_api_subdivsurf_pop] 
mi_api_subdivsurf_end 


n is 3 or 4 for triangles or quads, respectively, plus either 1 (base polygon) or 4 (polygon kit) if 
the object is tagged, in which case the triangle/quad labels must be passed first. A “kit” consists 
of 3 or 4 indices that subdivide the edge of the parent polygon into four sub-polygons, each of 
which may have its own material (part of the kit) and each may in turn be subdivided (using up 
to four separate push/pop blocks). 
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miBoolean mi_api_subdivsurf_begin( 
char *name ) /* name of the surface */ 


Begin the definition of a subdivision surface with the given name. The name is valid only inside 
the object group. 


miBoolean mi_api_subdivsurf_baseface (void) 


Define a base triangle or quad. Before calling this function there must be either 3 or 4 vertices 
specified with mi_api_subdivsurf_index. If the object is tagged, one additional index must be 
specified, for a total of either 4 or 5. 


miBoolean mi_api_subdivsurf_mt1 ( 
int child, /* 0-3 */ 
char *mt lname) /* material name or 0 */ 


Add a material to the current face. A face may have only one material. child specifies to which 


child of the current kit the material is assigned. If the current face is a base polygon, -1 must be 
passed for child. 


miBoolean mi_api_subdivsurf_mtl_tag( 
Int child, 
miTag mtltag) /* material tag or 0 */ 


This function is equivalent to the previous but specifies the material as a tag. 


miBoolean mi_api_subdivsurf_index ( 
int idx) /* another base face vertex index */ 


If the object is tagged, the first index specified by this function is interpreted as a face material, 
subsequent indices specify base face vertices. If the object is not tagged, only the three or four 
vertex indices may be specified. When using this function for detail vector specification, object 
tagging is not admissible since materials are specified in other ways for kits. The first index 
specified will directly correspond to the first detail vector, even if tagging is enabled. 


miBoolean mi_api_subdivsurf_push(void) 


This function prepares a face subdivision. It must be called immediately before mi_api_subdivsurf- 
subdivide. The purpose of this function is to save the current face context, i.e. current face and 
level. 
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miBoolean mi_api_subdivsurf_pop (void) 


When a face subdivision is completed, this function must be called to restore the state as it was 
before face subdivision. 


miBoolean mi_api_subdivsurf_subdivide( 
int child) 


This function subdivides the specified child of the current kit. It must be called after mi_api_ 
subdivsurf_push. Initially no detail vectors are assigned to the vertices. If the current face is a base 
polygon, -1 must be passed for child. 


miBoolean mi_api_subdivsurf_detail ( 
int mask) 


This function sets detail vectors for the current face and for the current level. A vertex may have 
details beginning with the vertex definition level, and also on higher levels. mask specifies which 
vertices of the current kit will have details. This parameter is a bitmap. Bit 0-2 for triangles and 0- 
3 for quads specify whether the even vertices of the kit have details, bits 3-5 for triangles and 4-6 
for quads specify whether the odd vertices of the kit have details. Detail vectors must be specified 
before calling this function with enough calls to mi_api_subdivsurf_index. These detail vectors are 
associated to the kit vertices using the mask bitmap. The current face must be a kit. 


miBoolean mi_api_subdivsurf_crease_edge( 
miScalar value) 


Specifies the sharpness for a crease edge, in the range 0..1. 


miBoolean mi_api_subdivsurf_crease ( 
int chili, 
int mask) 


This function defines a crease edge for the current face. The face is specified with child, for base 
polygons -1 must be given for child. The crease edges are specified with the bitmap mask. Bits 0..2 
for triangles and 0..3 for quads specify the edges to be used for the crease. It is sufficient to mark a 
crease edge only in one direction, the other direction is marked automatically. Before calling this 
function enough crease sharpness values must be specified with calls to mi_api_subdivsurf_crease- 
edge. The bitmap mask is used to associate the sharpness values to the selected crease edges. 


miBoolean mi_api_subdivsurf_trim( 
int child. 
int mask) 
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This function defines a trim edge for the current face. The face is specified with child, for base 
polygons -1 must be given for child. The trim edges are specified with the bitmap mask. Bits 0- 
2 for triangles and 0-3 for quads specify the edges to be used for the trim edge. The current face 
will be located inside the trimmed region, i.e. it is cut out of the surface. 


Trim edges must form a connected loop on the same level. Connected trim edges must be defined 
on the same level in the hierarchy. A trim edge may not be defined on the outer boundary loop 
of the subdivision surface. Nested trimming regions are not supported, i.e. it is only possible to 
define a single level of trim regions, not trim regions within trim regions. Edges of two different 
trim regions may not share the same edge or vertex. Trim regions may not overlap, intersect or 
touch. 


miBoolean mi_api_subdivsurf_end (void) 
Complete the definition of the subdivision surface started with mi_api_subdiv_begin. 


miBoolean mi_api_subdivsurf_approx ( 
char *name , 
miApprox *kapprox) 


Change the default approximation of a subdivision surface with name name to approx. 


miBoolean mi_api_subdivsurf_approx_displace( 
char *name , 
miApprox *approx) 


Change the default displacement approximation of a subdivision surface with name name to 


approx. 


miBoolean mi_api_subdivsurf_derivative( 
int degree, 
int space) 


Enable computation of derivatives for the current subdivision surface. degree must be 1. space 
selects which texture space should be used for the parameterization of the subdivision surface. 


typedef struct miApi_texspace_options { 
miBoolean face; 
} miApi_texspace_options; 


miBoolean mi_api_subdivsurf_texspace ( 
miApi_texspace_options *opt, 
miUint no_opt) 
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>> This function sets the interpolation methods used for the defined texture spaces: if face is 
miTRUE, textures are evaluated per face (faceted) instead of being interpolated between vertices, 
which is the default. The method must be selected in the options array passed to this function. 
The array has one member for each texture space; no_opt is the number of array members. 


4.2.8.9 Triangle List Objects*~ 


Triangle list objects provide a way of directly specifying the renderable representation of geometry 
in mental ray, which is boxes of triangles. Displacement mapping may still be applied. Triangle 
list objects are more efficient in terms of storage and runtime than polygon objects because no 
tessellation or other operation are performed that copy data. However, since triangle lists expose 
data structures used for rendering, they may change at any major update of mental ray which 
requires changing the code that uses them. mental ray 3.4 supports a different data structure called 
primitive lists that replace trilists. Use with care, and expect incompatibilities with new major 
versions of mental ray. 


miGeoBox * mi_api_trilist_begin( 


miVertex_content *VC, 

miUVint no_vectors, 
miUint no_vertices, 
miUint no_triangles) 


Begin definition of a triangle list object. The vertex layout is specified in vc, the other parameters 
specify the number of vectors, vertices and triangles for the object. 


Returns a pointer to the low level result structure of a triangle list object, which is a miGeoBox. 
Instead of using mi_api_trilist_vectors, mi_api_trilist_vertices, mi_apt-trilist_triangle or mi_apt- 
trilist_triangles for geometry specification, the returned box may be initialized directly with 
help of the miBOX_GET_VERTICES and miBOX_GET_PRIMITIVES macros. 


miBoolean mi_api_trilist_approx ( 
miApprox *approx) 


Attaches a displacement approximation to the current triangle list object. 


miBoolean mi_api_trilist_vectors ( 
miVector *vectors, 
miUint no_vectors) 


Appends no_vectors vectors to the triangle list. The vectors array is not released by this function. 


miBoolean mi_api_trilist_vertices( 
miGeoIndex *vertices, 
miUint no_vertices) 
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Appends no-_vertices vertices to the triangle list. Each vertex requires corresponding vc — sizeof - 
vertex integers in the vertices array. The vertices array is not released by this function. 


miBoolean mi_api_trilist_triangle( 
char *material, 
miGeoIndex *indices) 


Defines a single triangle with a named material. The indices array contains exactly three triangle 
indices referencing the vertex section of the box. The material string must be allocated and is 
released by this function, but the indices array is not released. 


miBoolean mi_api_trilist_triangles( 
miGeoIndex *indices, 
miUint no_triangles) 


Defines multiple triangles. The number of trinagles is specified in no_triangles. The triangle 
vertices are specified in the zdices array. If the triangle list object has been created with the tagged 
flag, the material index must be given first in the index array, followed by the three triangle 
vertices. These three or four index groups must be repeated no_triangles times. The indices array 
is not released by this function. 


miBoolean mi_api_trilist_end(void) 
Completes the definition of a triangle list object. 


4.2.8.10 Primitive List Objects’ * 


Primitive list objects replace trilists in mental ray 3.4. Native trilists are no longer supported. 
The miGeoBox data structure has been replaced by the new type miBox. The trilist family of 
API functions can still be used for defining triangle objects, however maximum performance is 
achieved by using the primlist functions described below. 


miBox *mi_api_primlist_begin( 
miVertex_info *info, 


miUint no_lines, 
miUint no_prim_lists, 
miUint no_indices, 
miUint no_materials, 
miUint pd_size, 
miUint no_prims) 


The current object being created is set to type miOBJECT_BOXES and a scene element of type 
miSCENE_NBOX is created. no_lines specifies the number of vertex lines containing floating point 
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vertex data, no_prim_iists is the number of primitive lists requested. Each primitive list contains 
multiple primitives of the same type. In mental ray 3.4, 20_prim_lists must be 1 and only primitives 
of type miSCENE_PRIM_TRI are supported. The number of primitive indices (references to the 
vertex lines) is given with no_indices, the number of materials with no_materials. In mental ray 
3.4 there must be a corresponding material entry defined for each primitive (triangle). The total 
number of primitives in all primitive lists is given with no_prims. Each primitive may have user 
data attached to it, pd_size specifies the total size reserved in the miBox. 


miBoolean mi_api_primlist_dimensions ( 
miUint *tex_dims, 
miUint *xuser_dims) 


This function helps initializing the texture and user offset section in a miBox. Both tex_dims and 
user_dims specify the dimension for each texture/user space defined in the box. Memory for both 
arrays is not released by this function. 


miBoolean mi_api_primlist_approx ( 
miApprox *approx) 


Attaches a displacement approximation to the current primlist object. 
miBoolean mi_api_primlist_end(void) 

Completes the definition of a primlist object. 

4.2.9 Function Declarations 


Functions are user-written C routines with parameters that are used as shaders during 
preprocessing, rendering, and postprocessing. Before a function can be defined (by giving its 
name and listing its parameter values), it must be declared so mental ray knows the complete 
parameter list the C function accepts, and the data type for each parameter. For a complete list of 
available shaders, refer to the mental ray manual. 


miParameter *mi_api_parameter_decl ( 


miParam_type type, /* one of miTYPE_* */ 
char *xname , /* parameter name */ 
int strlength) /* not used */ 


Before the function itself is declared, a complete description of the parameters and their types 
must be built. This function builds amiParameter structure for a single parameter to be appended 
to the list. The parameter type, the parameter name, and the maximum length of the string if the 
type is miTYPE_STRING, must be specified. The string length includes the trailing null byte. 
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miParameter *mi_api_parameter_append( 
miParameter *list, /* list of parameters */ 
miParameter *parm) /* new parameter */ 


Parameter structures created with the previous function must be concatenated to a list with this 
function. It appends a new parameter parm to an existing list ist. The parameter pointer created 
with the definition of the first parameter, which is also the anchor of the parameter list that will 
be passed to mi_api_funcdecl_end, can be used as list argument, but it is more efficient to pass the 
parameter pointer returned by the previously appended parameter. 


miBoolean mi_api_parameter_child( 
miParameter *parm, /* struct or array */ 
miParameter *child) /* str/array to attach */ 


Function parameter lists are not necessarily linear lists. Parameters of type miTYPE_STRUCT and 
miTYPE_ARRAY require a sublist of parameters. Arrays always require a single parameter as subtree, 
which becomes the type of the array, while structures require a list as subtree that contains one 
parameter for every member of the structure. The sub-parameter or sub-parameter list child is 
attached to the array or structure parameter parm with this function. 


miFunction_decl *mi_api_funcdecl_begin( 


miParameter *xoutparms, /* result parameters */ 
char *xname , /* function name */ 
miParameter *xinparms) /* parameter list */ 


After the parameter list (or tree, if arrays and structures are present) has been built, the function 
itself can be declared. The return parameter, the function name (which must agree with the name 
of the C function to be executed), and the anchor of the parameter list must be passed. This call 
completes the declaration of a function. 


The result parameter list is similar to the input parameter list, but may only be either a simple type 
or a structure, not an array or a structure containing structures or arrays. The result parameter 
does not have a name (1.e. the name argument in the call to mi_api_parameter_decl that returned 
outparms was a null pointer), but if the result parameter is a structure, the structure members 
must be named as usual. The outparms pointer should be a null pointer if a structured user data 
block is being declared (see mi_api_data_begin). This function always stores the declaration type 
miFUNCTION_C, so if a phenomenon or user data block is being declared, the caller must modify 
the type field of the returned declaration. 


Earlier versions of the API passed a miParam_type instead of amiParameter. This was changed 
to allow structured return types. For backward compatibility, mi_api_funcdecl_end still accepts 
miParam_type codes, but since the function prototype changed the compiler will generate an 
error unless a cast is applied. 
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miTag mi_api_funcdecl_end(void) 


After the function declaration is finished, this call finishes the declaration and returns the tag of 
the new database element. 


4.2.10 Function Definitions 


Functions, also called function calls, are references to a particular C function bundled with a set 
of parameter values. A function definition begins with naming the desired C function, which 
must have been declared (see above), followed by assignments of numerical or other values to 
individual parameters. The order of assignments is irrelevant; it is done by parameter name. 
Parameters that remain unassigned have a numerical value 0 or the empty string. 


miBoolean mi_api_function_call( 
char *name ) /* called function */ 


Every function definition begins with this call, which references the C function by name. An error 
occurs if the name is not declared. This function is special in that it does not insist on name to be 
declared in the current scope (see Scopes below). Instead, it searches for the function beginning 
in the innermost scope and works back towards the outermost scope. This is useful because 
shader declarations usually appear in the form of a $include statement at the beginning of the 
scene file, it would be inconvenient to force a redeclaration in every scope (such as phenomenon 
definitions) just to have the correctly scoped names handy. 


miBoolean mi_api_parameter_name ( 
char *name ) /* new parameter */ 


After mi_api_function-_call, the parameter values are assigned. The first step for an assignment is 
this call, which specifies the name of the parameter to be assigned to. The name must be one 
of those specified when the function was declared. name is always a simple name; to access the 
subtrees of arrays and structs special functions (push, pop, array element) are provided, see below. 
Parameter names may not contain dots (“.”). 


miBoolean mi_api_parameter_default ( 
miParam_type type, /* one of miTYPE_* above */ 
void *value) /* ptr to int, float, bool */ 


>> Store a parameter default value for the parameter declared with the preceding mi_api_parameter- 
decl call. The value must point to a miBoolean, miInteger, or miScalar, depending on the 
parameter type. Correspondingly, the type argument must be one of miSCENE_BOOLEAN, miSCENE_ 
INTEGER, and miSCENE_SCALAR. Integers are automatically converted to scalars if the declared 
parameter type requires it. To declare all three components of a vector, or all four components 
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of a color, or all sixteen components of a transformation, it must be called three, four, or sixteen 
times. Non-numeric types and array members may not have defaults. 


miBoolean mi_api_parameter_value( 


miParam_type type, /* parameter type */ 
void *value, /* pointer to value */ 
int *null, /* null pointer */ 

int *size) /* size in parm block */ 


Assign a value to the parameter named with the previous call. The type of the value being assigned 
and a pointer to the value must be passed. The type must agree with the declared type of the 
parameter, following these rules: 


e For all textures miTYPE_TEX must be used, regardless of whether a color, scalar, or vector 
texture has been declared. 


e Instead of miTYPE_SCALAR, miTYPE_INTEGER can be passed. The value will automatically be 
converted to a miScalar if the parameter has been declared as mi TYPE_SCALAR. 


e Similarly, a type of miTYPE_STRING can be passed for parameters declared as miTYPE_TEX, 
miTYPE_LIGHT, miTYPE_SHADER, miTYPE_MATERIAL, or miTYPE_GEOMETRY. The value will 
be interpreted correctly. 


e A type of miTYPE_INTEGER can be passed for parameters declared as miTYPE_TEX, 
miTYPE_LIGHT, miTYPE_SHADER, miTYPE_MATERIAL, or miTYPE_GEOMETRY. The value will 
be interpreted as a numeric tag. This is a deviation from the similarity between .mi syntax 
and API calls, but simplifies matters for automatic procedural construction of phenomena. 


e Values consisting of multiple scalars, such as vectors, colors, and matrices, can be given 
piecewise, one miTYPE_SCALAR at a time. If fewer than three scalars for a vector, four scalars 
for a color, or sixteen scalars for a matrix (row-major order) are provided, the remaining 
scalars are set to zero. 


These rules are all consequences of the fact that a .mi2 language parser, when it sees a value, does 
not have access to the declaration. 


The passed null pointer must be a null pointer. It exists only for backwards compatibility of the 
function prototype. The size pointer must be either a null pointer or a pointer to an integer that 
will be set to the size in bytes of the parameter. For example, if type is miTYPE_VECTOR, mi_api- 
parameter_value will set it to 12 (sizeof(miVector)). 


miBoolean mi_api_parameter_shader ( 
char *name ) /* shader name */ 


Instead of providing a value to a parameter, register another function by name that is called at 
runtime to calculate the value. This is used to build dynamic shader trees. 
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miBoolean mi_api_parameter_interface( 
char *xname ) /* interface parm name */ 


Instead of providing a value to a parameter, register a link to an interface parameter that provides 
the value at runtime. 


miBoolean mi_api_parameter_push ( 
miBoolean is_array) /* pushing array? */ 


After the call to mt_api_parameter_name for a structure or array, before values can be stored, 
the context must be pushed one level down into the structure’s or array’s parameter subtree. 
The is_array argument is miFALSE for structures and miTRUE for arrays. After the push, structure 
members and array elements can be assigned with regular mi_api_parameter_value calls. Every 
new array member must be preceded with a call to the following function. 


miBoolean mi_api_new_array_element (void) 


After the push operation, before a new array value can be assigned, this function must be used 
to make room for another array element. After the first call to this function, mi_api_parameter- 
value assigns to array element [0], after the next [1] is assigned, and so on. Array elements can 
only be assigned sequentially. If no values or not enough values are assigned to a parameter, its 
remaining scalars remain zero. 


miBoolean mi_api_parameter_pop (void) 


After a structure or array has been assigned its component values, the parameter subtree of the 
structure or array must be exited with a pop operation. For example, to assign the scalars 1 and 2 
to members a and b of structure s, the call sequence is name(s), push, name(a), value(1), 
name(b), value(2), pop. The order of assignment to a and b is not significant. To assign 3 
and 4 to an array a of length 2, the call sequence is name(a), push, new-element, value(3), 
new_element, value(4), pop. Push/pop pairs can be nested. 


miTag mi_api_function_call_end( 
miTag oldtag) /* for incr change */ 


After all parameter values have been assigned, the function definition is completed with this 
call. The tag of the new function is returned and can now be used where a function is expected 
during scene definition. Since functions (as opposed to declarations) are not generally named, the 
standard incremental method cannot be applied; therefore a tag argument can be supplied. If tag 
is not the null tag, the existing function identified by tag is replaced with the new one such that 
all references in the scene that referred to the old function now refer to the new one. In this case 
tag is also returned. 
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miTag mi_api_function_append( 
miTag iF: 5 /* append to this list */ 
miTag func) /* function to append */ 


Most regular shaders (not output shaders and inheritance functions) can be given as a list of 
shaders. In this case mental ray will call all shaders in the list in sequence, with each successive 
shader operating on the result of the previous. The main application are lens shaders, which are 
often lists of lens shaders. To append a function func to another function or function list /zst this 
call is used. The first function in the list is the anchor of the list; it can be passed as list when 
appending to the list but it is more efficient to pass the last function added to the list. 


miBoolean mi_api_function_delete( 
miTag *xlist) /* func list to delete */ 


When a scene element referencing functions is changed incrementally, it is usually desired to 
delete the old function list before a new one is built with calls to mi_api_function_append. This 
call deletes all functions of the function list, and stores a null tag in the list anchor. The /ist 
argument is a pointer to the function list tag to permit this call to clear the function list tag itself. 


miBoolean mi_api_shader_add( 
char *name , /* shader name */ 
miTag func_tag) /* shader function */ 


Normally functions are unnamed. This call can be used to assign a name to a function. The main 
application are procedural textures, which are nothing but a texture shading function accessible 
by name (the name can be provided as parameter value to texture parameters of other functions). 
Named shaders also appear in the .mi2 language as shader statements. Note that lights, materials, 
and other scene elements are more than just shading functions, a named shader cannot be used 
where a material or light is expected. 


miTag mi_api_function_assign( 
char *name ) /* name of shader */ 


This call can be used to look up a named shader (was given a name by the preceding call) to obtain 
its tag. The returned tag can be used like a tag returned by mz_api_function_call_end. This is called 
an “assignment” because the .mi2 language allows assigning an existing named shader wherever 
a shading definition is called; such assignments are introduced with an equals sign. 


miBoolean mi_api_shader_call( 
miTag func_tag, /* function to call */ 
char *c_inst_name, /* camera instance */ 
char *xoption_name) /* options element */ 
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This function can be used to call a shading function immediately. This call returns after the called 
function returns. If func_tag is a function list, all functions in the list are called in sequence. 
The functions are provided with a dummy state containing mostly nulls; if a camera instance or 
options element are passed by name, appropriate camera and options substructures are placed in 
the state. Either c_inst_name or option_name may be null pointers. 


miBoolean mi_api_shader_call_x( 


miColor *result, /* returned color */ 

miTag func_tag, /* function to call */ 
char *c_inst_name, /* camera instance */ 
char xoption_name, /* options element */ 
void *data) /* extra user data */ 


**'This is a variant of mi_api_shader-call that can be used to call a shader, and retrieve a result 
from it. It is the caller’s responsibility to pass a result pointer to memory that is large enough to 
hold all the data that the shader returns, if it returns data other than a miColor. The data pointer 
is passed to the shader as its fourth argument, and is not otherwise touched or dereferenced by 
mental ray. 


4.2.11 Phenomenon Definitions 


Phenomena are declared after all the subshaders to be used inside the phenomenon have been 
declared. Inside the phenomenon, subshaders will be defined, complete with shader name and 
parameters. Parameters may have constant values, like in a regular shader definition, or they may 
have subshaders assigned to them, or they may have phenomenon interface parameters assigned to 
them. It is important to understand that the phenomenon declaration contains shader definitions. 


miFunction_decl *mi_api_phen_begin( 


miParameter *xoutparms, /* one of miTYPE_* */ 
char *xname , /* phenomenon name */ 
miParameter *xinparms) /* parameter list */ 


Begin the declaration of anew phenomenon name, along with its result and input parameters that 
must have been previously built with calls to mi_api_parameter_decl, mi_api_parameter_append, 
and mti_apt_parameter_child. 


miTag mi_api_phen_end (void) 


After the declaration returned by the previous function has been set up, this function terminates 
the phenomenon declaration. If an error occurs, a null tag is returned; otherwise the tag of the 
new phenomenon element is returned. The type of the returned element is miSCENE_FUNCDECL. 
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4.2.12 Verbatim C Sources 


In most cases, compiled C shading functions will be linked to the program as shared libraries. 
The library can also link existing object files and C source files. This is handled by the LINK 
module and is outside the scope of the API module. However, API allows verbatim specification 
of C sources as part of the scene definition with the following three calls. Use of these functions 
is discouraged except when parsing .mi2 scene files because the overhead is significantly higher 
than linking shared libraries. 


miBoolean mi_api_code_verbatim_begin (void) 


Begin the definition of verbatim code. This call opens a temporary file in /usr/tmp with a unique 
file name that receives the C sources. 


miBoolean mi_api_code_byte_copy ( 
int length, /* # of data bytes */ 
miUchar kbytes ) /* C src data array */ 


Append ascii source text to the C source file opened by the preceding call. The bytes string is 
expected to contain length characters, not counting a trailing null byte (which i is not required). 
The bytes pointer, like any other string passed to an API call, is released using mi_mem-release. 


miBoolean mi_api_code_verbatim_end (void) 


After the sources have been stored with one or more byte copy calls, this call completes the 
verbatim source definition. The temporary file is closed, compiled, linked, loaded, and removed. 


4.2.13 Scopes 


Scopes disambiguate name spaces. The current scope is defined by a string that is prepended to 
all toplevel element names (objects, materials, lights, functions, declarations, etc) passed to API. 
Non-toplevel entities such as surfaces, curves, and shader parameters whose lifetime are limited 
to the enclosing toplevel element are not scoped. The scope string is initially empty. REOHES can 
be nested. Scopes in the scope string are separated by double colons; the scope string “a: :b: 


the result of first beginning scope “a” and then scope “b”, If applied to a name “x”, the tes 


name is “a::b::x”. Since symbol tables contain scoped names, this can be used to distinguish 
different *x”. 


For example, mi_api_phen_begin automatically begins a new scope with the phenomenon name. 
This causes the phenomenon name and a double colon to be prepended to all shaders defined 
inside the phenomenon, which allows different phenomena to have subshaders with the same 
name. If phenomena “phen1” and “phen2” both have a subshader “shader”, no conflict arises 
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because their internal names are “phen1: : shader” and “phen2: : shader”. The scoping functions 
are available to other modules, for example to allow the shader editor to read a declaration file 
without causing conflicts with the loaded scene. The name of the declared phenomenon itself, 
like the name of any other declaration, is global and does not get a scope prepended. 


Every context has its own scope string (see LIB module about contexts). 


miBoolean mi_api_scope_begin( 
char *name ) /* new scope name */ 


Enter a scope. The given mame and two colons (in this order) are appended to the scope string. 
miBoolean mi_api_scope_end (void) 
Exit a scope. The last name and double colon is stripped off the scope string. 


char *mi_api_scope_apply ( 
char xname) /* name to put in scope */ 


Prepend the scope string to name, if any. If name contains double colons, check the scope part 
of name against the scope, and return a null pointer if the check fails. For example, it is an error 
for name to contain double colons if there is no scope; assuming that the scope is “a: :b::”, the 
names “x”, “b::%", and “a::bs x” are all ok and return the same strine “ai :b::x” but “a: ix” 
is an error. As usual, name must have been allocated using MEM functions. The returned string 


is allocated with MEM and may be identical to name. 


The following functions accept char* arguments that are passed through mu_api_scope_apply 
automatically by API: 


mi_api_delete mi_api_delete_tree mi_api_options_begin 
mi_api_camera_begin mi_api_render mi_apitlight_begin 

miapitlight_lookup miapi_material_begin m1_api_material_lookup 
mi_api_texture_begin mi_api_texturelookup = mi_api_instance_begin 
mi_api_instance_end mi_apiinstgroup_begin mi_apiinstgroup_additem 
mi_api_object_begin mi_api_poly_begin mi_api_surface_begin (material name only) 
miapifunction_assign m4i_api_—function-_call mi_api_parameter_shader 
mi_api-shader_add mi_api_shader call 


4.2.14 Miscellaneous 


miBoolean mi_api_delete( 
char *what ) /* element to delete */ 
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Delete a single element from the scene database. This function may be used only after all references 
to the element have been deleted. For example, before deleting an object all instances referencing 
it must be deleted, or incrementally changed to reference something else, and so on. 


miBoolean mi_api_delete_tree( 
char *what ) /* element to delete */ 


Delete a tree anchored at the named element in the scene database. This function takes care of 
deleting all members of the tree in the proper order such that references to an element are removed 
before the element itself is deleted, but only within the named tree — multiple instancing from 
outside is not recognized, and outside references to what itself are also not removed. 


miBoolean mi_api_delete_tree( 
char *what ) /* element to touch */ 


°-> Mark the named toplevel scene element for re-evaluation. This is useful to mark objects for 
retessellation when a displacement shader or one of its direct or indirect subshaders changes 
(mental ray cannot discover this by itself), or when the contents of a texture file have changed on 


disk and need to be reloaded. 


miBoolean mi_api_debug( 
char *what , /* what to dump */ 
char *karg) /* if scene dump, item */ 


This function 1s useful for debugging code that calls the API module. It is not essential for scene 
definition. The what argument specifies what to check, and the arg argument specifies the name 
of a scene element to be checked, depending on what is being checked. The following what strings 
are supported: 
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sym global 
sym declare 
sym options 
sym camera 
sym light 
sym object 
sym instance 
sym group 
sym material 
sym ctexture 
sym stexture 
sym vtexture 
mem summary 
mem dump 
mem check 
db statistics 
db dump 
task statistics 
img verbose 


scene check element 
scene dump element 
scene alldump | element 
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operation 


print all symbol tables 

print the global (.mi2) symbol table 

print the declaration symbol table 

print the .mil options symbol table 

print the .mil camera symbol table 

print the .mil light symbol table 

print the .mil object symbol table 

print the .mil instance symbol table 

print the .mil instance group symbol table 
print the .mil material symbol table 

print the .mil color texture symbol table 
print the .mil scalar texture symbol table 
print the .mil vector texture symbol table 
print per-module MEM memory usage summary 
print all allocated MEM memory blocks 
run a consistency check on MEM memory 
print DB database access statistics 

print a list of all DB database entries 

print TASK task queue statistics 

future image file accesses print messages 
consistency check of a scene element 
recursively print info on scene element 
recursively print detailed element info 
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This chapter describes the data structures that define a scene in memory. While the scene is 
constructed using API calls, there is not an API call for all operations that merely write a value 
into an existing data structure. Instead, the mi_api_*_begin calls return a pointer to the data 
structure just created and expect the caller to fill in simple parameters. This chapter describes 


these data structures. 


This section discusses every element type in detail. There is one subsection for each element type. 


Each describes 


e the element type (as returned by mi_db_type), 


e the C data type of the contents. Some elements are arrays of this type. 


e the extra arguments given to the create and resize functions to preallocate variable-sized 


sections. 


e a brief descriptions of the defaults stored by the create function. 


e the declaration of the data type, with description. 
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This chapter describes the data structures used by mental ray 3.x. The data structures for mental 


4 Geometry Shaders 


ray 2.1 are similar, but lack a number of fields. These fields are marked “**”. 


4.3.1. Instances 


Element type: 
Data type: 
Sizes: 
Defaults: 


enum miGenMotionType { 


miSCENE_INSTANCE 
mulnstance 

int param_size 

all nulls, two identity matrices, parameter size as given by size argument 


miGM_INHERIT = 0, 


miGM_TRANSFORM, 


miGM_OFF 
Bae 


typedef struct miTransform { 


miTag 
float 
miMatrix 
miMatrix 
miCBoolean 
miCBoolean 
int 

} miTransform; 


function; 

time; 
global_to_local; 
local_to_global; 
identity; 

spare [3]; 

i Ts 


typedef struct milInstance { 


miTransform 
miMatrix 
miTag 
miTag 
miTag 
miTag 
miTag 
miTag 
int 
miTag 
milag 
miUint 
miTag 
miCBoolean 
miUint1 
miUint1 
miUinti 
miUint1i 
miUinti 
miUint1i 
miUinti 
miUinti 
miUinti 


ti; 
motion_transform; 
item; 

material; 
parent ; 

boxes; 

next; 

prev; 
mtl_array_size; 
light_obj_ring; 
userdata; 
label; 
geogroup; 

Ori; 
gen_motion; 
visible; 
shadow; 
reflection; 
refraction; 
transparency; 
caustic; 
globillum; 
finalgather ; 


/* 
/* 
/* 
/* 
/* 
/* 
/* 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
o* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


function, may be null tag */ 
the last evaluation time */ 
transformation in world */ 
transformation to world */ 
SCENE: matrices are ident.*/ 
SCENE: not used */ 

SCENE: unique transform ID*/ 


space transformation */ 
motion transformation */ 
instanced item */ 

inherited material or list*/ 
SCENE: leaf inst. parent */ 
SCENE: renderable repres. */ 
SCENE: leaf instance list */ 
SCENE: leaf instance list */ 
if mtl array, array size */ 
SCENE: obj-light links */ 
optional user data blocks */ 
optional label */ 

SCENE: geomshader group */ 
ignore this instance */ 
motion information */ 
visible ? */ 

casts/receives shadow? */ 


casts/receives reflections? */ 
casts/receives refractions? */ 
casts/receives transparency? */ 


caustic bitmap */ 
globillum bitmap */ 
finalgather bitmap */ 
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char face; /* a=all, f=front, b=back */ 
miCBoolean temp_material; /* SCENE: has inherited mtl */ 
miUint1 select; /* selectable when picking? */ 
miCBoolean mtl_override; /* inst mtl overrides obj mt1l*/ 
miUshort history_size; /* leaf inst: # of hist tags */ 
miTag approx_list; /* 10 inherited miApprox’s: */ 
/* ¥,€,8,¢,@, diepl v,t,3,c,2%/ 
miCBoolean approx_override; /* inst approx overr. obj app*/ 
miUint1 hardware; /* render inst. with hardware */ 
miUint1 shadowmap ; /* casts shadowmap shadows? */ 
char spare; /* not used */ 
miTag param_decl; /* parameter declaration */ 
int param_size; /* parameter size in bytes */ 
char param [8] ; /* arbitrary-sized parameters*/ 


} milnstance; 


A translator must provide: either tf.function and time, or global_to_local and local_to_ 
global; also item (using mi_scene_link), param_decl, param_size, and param. 


All fields except the matrices, the material, and the parameters are reserved for Scene and may 
not be modified by other modules. The tags can be modified indirectly with the link and unlink 
functions, which take care of reference counts. The instance element has two variable parts; one 
for inherited shader parameters and one for the relation list. The latter is maintained internally 
by mental ray. 


tf.function optionally points to a transformation function that computes a matrix from the 
current time. If present, this function is called during preprocessing with three parameters: 
a pointer to the result global—to-local matrix, the instance tag, and the time as given in the 
preprocessing control structure. 


tf.time is the time the evaluation function, if present, was last called with. If it matches the current 
time, the matrices need not be calculated by calling the function again. 


tf.global_to_local transforms the parent space to the local space of the instanced subtree. If 
a transformation functions exists, it writes its result here; if not, the translator must store an 
appropriate matrix here. 


tf.local_to_global is the inverse matrix, set by Scene after the transformation function (if it exists) 
has returned the tf .global_to_local matrix. 


tf.identity is miTRUE if the transformation matrices in this instance are identity transforms (this 
saves the renderer unnecessary ray transformations). 


tf.id is a unique transformation ID. Scene creates it during preprocessing, trying to assign identical 
IDs to identical transformations. This is especially important for leaf instances: the renderer does 
not have to retransform the current ray if the new box has the same transformation (same ID) as 
the previous. 
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motion_transform specifies the transformation from parent space to local space for motion blur 
transforms. If this is a null matrix, the instance transformation tf is used. 


item is the tag of the element being instanced. Only groups, cameras, lights, objects, or functions 
can be referenced. If a function (or function list) is supplied, mental ray will call them during 
scene preprocessing as geometry shader. They must return a single object tag, which may (and 
often should) be a placeholder object. 


material is either a material (if mtl_array-_size is 0) or a material list (if mtl_array-_size is nonzero) 
used for material inheritance (as opposed to parameter inheritance). During scene preprocessing, 
the non-null material tag closest to a geometrical object (lowest in the DAG hierarchy) becomes 
the default material for any polygon or surface in the object that does not have its own non-null 
material tag. If the tag references a list (type miSCENE_TAG) or materials, it is expected to contain 
mtl_array-size tags, which will be indexed with the polygon or surface label during rendering. 
(The mtl_override’* flag modifies the inheritance rules, see below.) 


mtl_array_size specifies the number of tags in the material tag list if nonzero. If the material tag 
specifies a material directly, it must be zero. This number is used during rendering as a flag that 
tells mental ray that the material tag references a list, and also how many items there are in the 
list to prevent array bounds overflows. 


boxes is used by mental ray internally to store tessellation results in leaf instances created during 
preprocessing. 


next and prev are used by mental ray internally to chain leaf instances created during 
preprocessing. 


light_obj_ring®"' is used internally by mental ray to keep track of geometric area light sources*"’. 


userdata allows attaching a user data block (miUserdata) or a chain of user data blocks. Shaders 
can retrieve the data with mi_query. 


label’* stores an opaque integer set by the scene file with a tag statement. 


geogroup is used internally to point to the group element which contains all the geometry-shader 
created scene elements for this instance. 


off, if true, stops the recursive descent during preprocessing as if the instance and its instanced 
item didn’t exist. This is useful for temporarily suspending subtrees without deleting them. It 
implements the hide flag in the .mi grammar. 


gen_motion specifies that motion blur should be generated for the instance. Setting this field to 
miGM_OFF switches off motion blur for this instance. Motion blur is always generated when this 
field is set to miGM_TRANSFORM. The parent instance determines whether motion blur is active or 
not when gen_motion is set to miGM_INHERIT here. 


The visible, shadow, caustic, globillum, and select’ flags are inherited in the scene DAG. During 
scene preprocessing, the non-null flag in the DAG instance closest to a geometrical object (lowest 
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in the DAG hierarchy) is put into the leaf instance. Before rendering starts the leaf instance flags 
are merged with the object flags and stored in internal raylib rendering data structures. In the 
merging operation these flags are treated as "fuzzy booleans", that is, a zero value means that the 
flag is ignored (the object flag is taken), 1 disables the flag (even if the object has enabled it) and 2 
enables it (even if the object has not set the flag). The caustic bitmap has the same bit interpretation 
as the corresponding field in the miObject, but has three more bits defined here. Bit 2, if set, 
disables generation of caustics cast by this object. Bit 3, if set, disables receiving caustics. Bit 5, if 
set, enables photons to intersect with this object. In the merging, bit 0 and bit 1 of the leaf instance 
and object caustic bitmaps are logically combined with an OR operation followed by AND of the 
instance caustic bitmap bits 2 and 3, inverted and shifted right two times. Also in the merging, 
bit 4 of the leaf instance and object caustic bitmaps are logically ORed followed by an AND with 
bit 5 of the instance caustic bitmap inverted and shifted right one position. The globillum bitmap 
is similar to the caustic bitmap. 


shadow flag is a bitmap that controls casting and receiving of shadows separately. Bit 0 enables 
shadows cast from this surface, and bit 1 allow shadows to be received by (fall onto) this object. 
By default, bit 0 is 0 and bit 1 is 1 (mode 2). 


reflection, refraction, and finalgather>* flags replace the trace flag. Code that writes to the trace 
field must now write to these three flag bitmaps instead. Again, bit 0 enables casting and bit 1 
enables receiving, and the defaults are 0 and 1, respectively (mode 2). 


transparency’* flag that enables visibility of the surface to transparency rays, again separately 
for casting (bit 0) and receiving (bit 1). Unlike the other flags, both bits are on (mode 3) by default 
to ensure backwards compatibility. 


finalgather controls the final gathering mode: 1 enables final gather illumination casting, 2 enables 
final gather illumination receiving, 3 enables both, and 0 neither. Default is mode 0. of f means that 
the object is invisible to final gather rays, and on (the default) enables final gathering illumination 
interactions with this object. 


face controls face culling. The possible values are ’f’ (front), ’b’ (back), and ’a’ (all). If not 
specified, the culling flag given in the options or in the state is used. 


temp-_material is an internal flag that tells SCENE postprocessing that the material field contains 
a material that was created during preprocessing, and must be deleted on postprocessing. This 
happens if the inheritance function sets one or more of the material fields in its material argument, 
to implement CATIA aspect inheritance. 


mtl_override’* changes the inheritance rules for the material or material list stored in this instance. 
If true, and materials exist, this instance will override materials in instances lower in the DAG 
and in the object, instead of allowing lower materials to override higher ones. This is useful for 
implementing highlighting selections. 

history_size° is set in leaf instances, so that the inheritance function or traversal function®"' can 
use the miLEAFHISTORY’* macro to access the inheritance history, beginning at the scene root 
group (0), followed by the instance in the root group that led to the current location in the DAG 
(1), all the way to the current instance (history_size — 1). The macro accepts one integer argument 


2: 
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(0 for root group etc.) and returns a tag. For example, this is useful in inheritance functions for 
comparisons to a selection list and then setting a highlight material and mtl_override on a match. 
approx_list’:* implements flagged approximation inheritance. If nonzero, it is a tag of an element 
of type miSCENE_APPROX_LIST holding up to 10 approximations, in the order visible, trace, 
shadow, caustic, globillum, displace visible, displace trace, displace shadow, displace caustic, and 
displace globillum. Approximations with multiple flags are stored in multiple slots. Unused slots 
have style miAPPROX_STYLE_NONE (see miApprox below). 


approx_override>~, if set, causes instances higher in the scene graph (closer to the root group) to 
override lower instances and object approximations. 


hardware?” specifies that the subtree must be rendered using OpenGL hardware. 


shadowmap”® specifies that the object casts shadows into shadowmaps, if the shadow flag is 
enabled as well. 


param_decl points to a parameter declaration that describes the parameters. If parameters exist, 
this tag must be set by the translator to allow data exchange with other hosts. If it is missing, no 
data will be swapped regardless of the remote host’s byte order. In leaf instances, Scene stores the 
most recent parent instance’s parameter declaration tag here. 


param_size is the size of the parameters in bytes. It is taken from the first and only argument of 
the create and resize calls. In the leaf instance, the inheritance function determines the size. 


param 1s an arbitrary-sized array of parameters stored by the translator. During preprocessing, 
the DAG is traversed, and the parameters are passed to an inheritance function that is called for 
every instance found during traversal. The end result is stored in the leaf instance by Scene. 


4.3.2. Groups 


Element type: miSCENE-GROUP 

Data type: miGroup 

Sizes: int max_kids, int max_connections 
Defaults: all nulls, max_* as given by size arguments 


typedef struct miGroup { 


miGeoScalar merge; /* merge tolerance */ 

miBoolean placeholder ; /* is this a demand-loaded group? */ 
int spare0O; /* not used */ 

miBoolean merge_group; /* perform merging on members? */ 

int max_kids; /* number of kids allocated */ 

int no_kids; /* number of kids actually used * / 
int max_connections;/* number of connections allocated */ 
int no_connections; /* number of connections used */ 
miTag userdata; /* optional user data blocks */ 
miUint label; /* optional label */ 


int spare1 [3]; /* not used */ 
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miTag kids [2] ; /* kid list (instances) */ 
} miGroup; 


typedef struct { 


miTag instance [2]; /* the two face type object instances*/ 
miGeoIndex face (2): /* indices of the two miFace’s */ 
miGeoIndex curve [2] ; /* indices of the two miCurves*/ 
miGeoRange range [2] ; 


} miConnection; 


A translator must provide: nothing. 
A translator may provide: merge_group, merge, the connection array, userdata, label. 


Groups have two variable-sized sections, one for the list of instances and one for the list of 
connections. The latter exists only if the group is a merge group. The macro miGROUP_GET_ 
CONNECTIONS (n) returns a miConnection pointer to the 2-th connection. Note that instances 
must be added to groups with mi_scene_link, but the connection tags are written directly to the 
miConnection. 

merge is the merge epsilon. It is used only in merge groups. 

placeholder?” is reserved for internal use. 

merge_group is miTRUE if this group is a merge group. Merge groups are treated like objects; all 
their subobjects are tessellated as one object. In fact, the Scene module treats merge groups like 
objects and lets GAP pick apart the group and its subtrees. 

max_kids is the current size of the kids array. 

no_kids is the number of instances stored in the kids array. 

max_connections is the current size of the connection array. 


no_connections is the number of connections in the connection array. 


userdata allows attaching a user data block (miUserdata) or a chain of user data blocks. Shaders 
can retrieve the data with mi_query. 


userdata°* allows attaching a user data block (miUserdata) or a chain of user data blocks. Shaders 
can retrieve the data with mi_query. 


label is a numeric value assigned by applications. 
kids is the beginning of the variable section of miGroup, consisting of an array of instance tags 
followed by an optional array of connections. Fields that follow the kids array in the C declaration 


in geoshader.h are not shown here, and are never used. 


The data structure contains extra members such as groupjob for placeholder groups, which are 
reserved for future extensions. Do not use. 
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4.3.3. Cameras 


Element type; miSCENE-CAMERA 


Data type: miCamera 
Sizes: —_ 
Defaults: as described below 


typedef struct miCamera { 


miBoolean orthographic; /* orthographic rendering? */ 
float focal; /* focal length */ 
float aperture; /* aperture */ 
float aspect; /* aspect ratio of the image */ 
miRange clip; /* min/max clipping */ 
int x_resolution; /* x resolution */ 
int y_resolution; /* y resolution */ 
struct tint xl, yl, xh, vhs 

window; /* corners of subwindow */ 
miTag volume; /* opt. volume shader */ 
miTag environment ; /* opt. environment shader */ 
miTag lens; /* opt. lens shader */ 
miTag output ; /* opt. output shaders/files */ 
int frame; /* current frame number */ 
float frame_time; /* ... as time in seconds */ 
int frame_field; /* O=frame, 1/2=field number */ 
float x_offset; /* x image offset in pixels */ 
float y_offset; /* y image offset in pixels */ 
miTag userdata; /* optional user data blocks */ 
miTag pass; /* opt. pass function chain */ 
float focus: /* not used */ 
float radius; /* not used */ 
miBoolean pass_mask; /* not used */ 
int spare[1i1]; /* not used */ 


} miCamera; 


A translator must provide: nothing. 
A translator may provide: all fields. 


orthographic (default miFALSE) switches the camera from the standard pinhole camera to an 
orthographic camera. 


focal (default 1.0) is the focal length of the camera (the distance between the camera and the 
viewing plane). 


aperture (default 1.0) is the width of the viewing plane in 3D space. 
aspect (default 1.0) is the height of a pixel 1 unit wide. 


clip (default 0.001, 1000000.0) describes the minimum (hither) and maximum (yon) limits of the 
scene for scanline rendering. Geometry outside these limits will not be rendered. 
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x_resolution (default 768) is the width of the rendered image in pixels. 

y-resolution (default 576) is the height of the rendered image in pixels. 

window (default 0, 0, 65535, 65535) describes the lower left and upper right corners of the 
rendered subwindow. Pixels outside this window will be black. If the upper right pixel exceeds 
the resolution, it is clipped to the resolution. 

volume (default miNULLTAG) is the optional atmosphere volume shader. 

environment (default miNULLTAG) is the optional view environment shader that is called for all 
(including primary) rays leaving the scene (the active environment shader for secondary rays may 
be overridden by materials). 

lens (default miNULLTAG) is the optional first lens shader. 


output (default miNULLTAG) is the optional first output shader or output file. 


frame (default 0) is the frame number of the current render. It is not used by mental ray but is 
accessible to shaders. 


frame_time (default 0.0) is the same as the frame number, but expressed in seconds. It is not used 
by mental ray. 


frame_field (default 0) is the number after the field substatement in a frame statement. Since 
frame numbers are integers, the field number must be used to distinguish the first and second 
field of the frame, if field rendering is in effect. By convention, 0 means that the entire frame is 
rendered; 1 is the first (odd) and 2 is the second (even) field. It is not used by mental ray. 


x_offset (default 0.0) is the x offset of the rendered image from the center of the camera axis in 
pixel units. 


y-offset (default 0.0) is the y offset of the rendered image from the center of the camera axis in 
pixel units. 


userdata allows attaching a user data block (miUserdata) or a chain of user data blocks. Shaders 
can retrieve the data with mi_query. 


pass’! (default miNULLTAG) is the optional first pass statement for multipass rendering. 


4.3.4 Lights 


Element type: miSCENE_LIGHT 
Data type: miLight 

Sizes: — 

Defaults: as described below 
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enum miLight_type { 
miLIGHT_ORIGIN, 
miLIGHT_DIRECTION, 
miLIGHT_SPOT 

¥3 


enum miLight_area { 

miLIGHT_NONE = 0, 
miLIGHT_RECTANGLE, 
miLIGHT_DISC, 
miLIGHT_SPHERE, 
miLIGHT_CYLINDER, 
miLIGHT_OBJECT, 
miLIGHT_USER 


}; 
typedef struct miLight { 
enum miLight_type type; /* light type */ 
enum miLight_area area; /* area? */ 
miScalar exponent ; /* global illum. 1/r7(2*exp) */ 
unsigned int caustic_store_photons;/*caus.photons to store*/ 
unsigned int global_store_photons; /*glob. photons to store */ 
miColor energy ; /* global illum. intensity */ 
miTag shader ; /* light shader */ 
miTag emitter; /* photon emitter shader */ 
miVector origin; /* opt. origin */ 
miVector direction; /* opt. normalized direction */ 
float spread; /* size of spot? (cos angle) */ 
union { 
struct miLight_rectangle rectangle; 
struct miLight_disc disc; 
struct miLight_sphere sphere; 


struct miLight_cylinder cylinder; 
struct miLight_object object; 


} primitive; /* area primitive */ 

short samples_u; /* area u samples */ 

short samples_v; /* area v samples */ 

short low_samples_u; /* low area u samples */ 

short low_samples_v; /* low area v samples */ 

short low_level; /* switch to low at this lvl */ 
miUint1 shadowmap_flags; /* indicate shadow map modes */ 
miUint1 dirlight_has_org; /* infinite light with org? */ 
miBoolean use_shadow_maps ; /* for this light */ 

miTag shadowmap_file; /* the shadow map file */ 

int shadowmap_resolution; /* resolution */ 

float shadowmap_softness; /* sample region size */ 

int shadowmap_samples; /* #samples */ 

miBoolean visible; /* visible? area lights only */ 
miUint label; /* light label */ 

miTag userdata; /* optional user data blocks */ 
unsigned int caustic_emit_photons; /* caus.photons to emit */ 
unsigned int global_emit_photons; /* glob. photons to emit */ 


miTag hardware ; /* hardware light shader */ 
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short shmap_h_min; /* not used */ 

short shmap_h_max; /* not used */ 

short shmap_v_min; /* not used */ 

short shmap_v_max; /* not used */ 

float transparent ; /* experimental shmap feature */ 
miScalar shadowmap_bias; /* move shmap Z back by bias */ 
struct miLight_shmap shmap; /* shadowmap data */ 

int spare2[2] ; /* not used */ 

} miLight ; 


struct miLight_shmap { 


miTag camera; /* optional camera for shadow maps */ 
miScalar accuracy ; /* detail shadow map min sample dist.*/ 
miScalar filter_u; /* currently only size 1 supported */ 
miScalar filter_v; /* currently only size 1 supported */ 
miSint2 samples; /* n*n samples per pixel */ 
miUchar filter; /* currently only box ’b’ supported */ 
miUchar type; /* detail shadow map: color or alpha */ 
}; 
struct miLight_rectangle { 
miVector edge_u; 
miVector edge_v; 
}; 
struct miLight_disc { 
miVector normal ; 
miScalar radius; 
}; 
struct miLight_sphere { 
miScalar radius; 
}; 
struct miLight_cylinder { 
miVector axis; 
miScalar radius; 


}; 
struct miLight_object { 


miTag object ; 
}; 


A translator must provide: type, shader, origin and/or direction and spread depending on 
type, all primitive fields for area light sources. 


type (default miLIGHT_ORIGIN) distinguishes between point lights (origin only), directional lights 
(direction only), and spot lights (origin, direction, and spread angle). 


area (default miLIGHT_NONE describes the type of area light geometry, and is one of miLIGHT_NONE, 
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miLIGHT_RECTANGLE, miLIGHT_DISC, miLIGHT_SPHERE, miLIGHT_CYLINDER, miLIGHT_OBJECT?!, 
and miLIGHT_USER>'!. 


exponent (default 2) controls the falloff of the light at a given distance. An exponent of 2 is 
physically correct, but other exponents can be chosen to make the light reach farther or less far 
than it should. An exponent of 1 means that the light energy does not fall off with distance. 
Exponents other than 2 disturb the energy balance in the scene. 


caustic_store_photons is the maximum number of photons from this light source to store in 
the caustic photon map. If set to zero, the number of photons to emit must be specified, which 
then controls the number of emitted photons no matter how many are stored. (The zero value is 
supported in mental ray 2.1.,37 and later, earlier versions require setting it to a very high number.) 


caustic_emit_photons is the maximum number of caustic photons to emit from this light source. 
Emission of caustic photons from a light stops when either caustic_store_photons or caustic_emit_ 
photons has been reached. 


global_store_photons is the maximum number of photons from this light source to store in the 
global illumination photon map. Again, a value of zero disables the store limit in mental ray 
2.1.37 and later. 


global_emit_photons is the maximum number of global illumination photons to emit from this 
light source. Emission of global illumination photons from a light stops when either globillum_ 
store_photons (if nonzero) or globillum_emit_photons has been reached. 


energy is the combined energy of all photons emitted by this light source. 


shader (default miNULLTAG) is the tag of a database element of type miSCENE_FUNCTION containing 
the light shader, which computes illumination by this light at render time. 


emitter (default miNULLTAG) is the tag of a database element of type miSCENE_FUNCTION containing 
the light photon emitter shader, which emits photons during the global illumination or caustics 
preprocessing phase. 


origin (default 0, 0, 0) is the origin of the light in object space. It is used only if type is miLIGHT_ 
ORIGIN or miLIGHT_SPOT. 


direction (default 0, 0, 0) is the direction of a directional light. It is used only if type is miLIGHT_ 
DIRECTION or miLIGHT_SPOT. 


spread is used only by spot lights and it specifies the size of the outer spotlight cone. 


primitive contains the size of the area light source if area is not miLIGHT_NONE. Depending on 
area, the width and height of the rectangle are given in rectangle.edge_u and rectangle.edge_v, or 
the orientation and radius of the disc are given in disc.normal and disc.radius, or the radius of the 
sphere is given in sphere.radius, or the axis and radius of the cylinder are given in cylinder.axis and 
cylinder.radius. All defaults are 0. For geometric area light sources*"', primitive — object.object 
must be an instance that references an object (not an object group). 
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samples_u (default 3) is the number of samples taken in the U direction of the area light source 
if area is not miLIGHT_NONE. 


samples_v (default 3) is the number of samples taken in the V direction of the area light source if 
area is not miLIGHT_NONE. 


low-samples_u (default 2) is the number of samples taken in the U direction of the area light 
source if area is not miLIGHT_NONE, when the trace depth specified by low_level is reached or 
exceeded. 


low_samples_v (default 2) is the number of samples taken in the V direction of the area light 
source if area is not miLIGHT_NONE, when the trace depth specified by /ow_level is reached or 
exceeded. 


low_level (default 3) is the sum of the reflection and refraction trace depth at which area light 
sampling switches from samples to low_samples. 0 means that no switching takes place and samples 
are always used. Ignored for user area lights. 


shadowmap flags’ is a bitmap containing the following settings: 


e miSHADOWMAP_MERGE °°merge the shadowmap on disk with the one being computed. Not 
available for detail shadowmaps. 


e miSHADOWMAP_CAMERA°*there is a camera attached to the shadowmap. 
e miSHADOWMAP DETAIL? This is a detail shadowmap. 


e miSHADOWMAP_ONLY°’*Only create shadowmaps, do not render. This is deprecated. Not 
available for detail shadowmaps. 


dirlight_has_org’* specifies whether the light is a directional light with origin or not. 
use_shadow_maps specifies whether shadowmaps are used for this light source. 


shadowmap_file is the tag of a string containing the filename for the shadowmap. If the tag is null, 
no file loading and saving will be done. For point lights and regular shadowmaps, six files will 
be generated, each with an identifying number (1...6) appended to the filename. If the file name 
contains the # character, it will be expanded to a hexadecimal number identifying the particular 
instance of this light. This allows different instances of a light to use different files. 


shadowmap_resolution is the resolution of the shadowmap. For point lights, the individual 
images will have a lower resolution, so that the total number of pixels rendered will be 
approximately shadowmap_resolution x shadowmap-resolution. 


shadowmap-softness when non-zero, enables soft shadows. The value given specifies the 
rectangular size of the region in the shadow map’s projection plane in which samples are placed. 
If this parameter is 0 only one sample will be used, creating sharp shadows. The size is given in 
internal space units on the shadowmap projection plane. 
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shadowmap-samples is the number of samples taken from the shadowmap. When shadowmap- 
softness is zero, this value is ignored. 


visible is miTRUE if the light should be seen in the rendering. This only applies to area light 
sources. 


userdata allows attaching a user data block (miUserdata) or a chain of user data blocks. Shaders 
can retrieve the data with mi_query. 


label is a numeric value assigned by applications. 
hardware?” is the hardware light shader. 


shadowmap bias? If this value is zero, then regular shadowmaps will use Woo’s method for 
calculating the depth value for the shadow map. This value is calculated as an average of the two 
closest intersections. This amounts to using a different bias for each pixel in the shadowmap. If 
a bias value other than zero is specified, then regular shadowmaps will only use the depth of the 
closest intersection. The bias will then be subtracted from the ray depth before a shadowmap 
comparison 1s made. The bias will only be applied to the ray depth, the shadowmap will store the 
original intersection depths. This allows to use the same shadowmap in memory or on disk with 
varying bias values without recomputing the underlying shadowmap. Detail shadowmaps cannot 
use Woo’s method, they always use a bias. If the bias value is set to zero, an internal method is 
used to compute a local bias. The numerical value of the bias is in internal units. 


shmap°? This struct contains shadowmap information relevant to shadowmaps. The filter related 
members of this struct are currently not used, but are reserved for future extensions. 


shmap.camera’’ An optional camera that may be used for shadow map settings. If used, the 
miSHADOWMAP_CAMERA flag must be set. 


shmap.accuracy’’ Determines how far two depths values within a detail shadowmap need to be 
apart to be considered different. A value if zero indicates that mental ray should try to determine 


a reasonable value. The numerical value is in the same internal units as shadowmap_bias. 


shmap.samples*’ determines the number of samples per pixel for detail shadowmaps. If samples 
is set to 7, then there will be 7 x 7 samples per pixel. 


shmap.type°’ selects whether detail shadowmaps should use colored shadows (value ’c’) or 
shadow intensities (value ’a’). 


The remaining fields are reserved and should not be used. 
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4.3.5 Functions 


Element type: miSCENE-FUNCTION 


Data type: miFunction 
Sizes: int param_size 
Defaults: all nulls 


enum miFunction_type { 


miFUNCTION_C, /* regular C/C++ shader */ 
miFUNCTION_PHEN , /* phenomenon interface */ 
miFUNCTION_C_REQ, /* C/C++ shader with regmnts */ 
miFUNCTION_OUTFILE, /* write an image to a file */ 
miFUNCTION_DATA, /* user data decl, no miFunc */ 
miFUNCTION_PASS_SAVE, /* write pass file */ 
miFUNCTION_PASS_PREP, /* pass file preprocessor */ 
miFUNCTION_PASS_MERGE, /* pass file merge function */ 
miFUNCTION_PASS_DELETE, /* pass file delete */ 
miFUNCTION_HARDWARE /* hardware rendering shader */ 
}; 
typedef struct miFunction { 
miPointer sparep1([7]; 
enum miFunction_type type; /* C/C++, phenomenon, or file*/ 
miUint out_typemap; /* if output, IMG_TYPE bitmap*/ 
miUint out_interpmap; /* if output, interpolate bm */ 
miTag function_decl; /* declaration if C or PHEN */ 
miTag next_function; /* next function call in list*/ 
miTag parameter_indirect; /* get params from this func */ 
miTag interfacephen; /* parent phen, if any */ 
miBoolean spare0; /* not used */ 
int parameter_size; /* size of parameter block */ 
int result_size; /* size of result struct */ 
int ghost_offs; /* offset to tag ghost, or 0 */ 
miTag pass_read; /* pass: infile, infile list */ 
miTag pass_write; /* pass: outfile or 0 */ 
miSint1 pass_maxsamples; /* pass: max samples or ~0O */ 
miCBoolean spare2[3]; /* not used */ 
miCBoolean no_expl_params ; /* candidate for indirect par*/ 
miCBoolean cloned; /* is this a clone */ 
miCBoolean spare3[5]; /* not used */ 
miUchar label; /* sequential # for bitmasks */ 
char parameters [8] ; /* parameter block, then */ 


/* miTag ghost for phenomena */ 
} miFunction; 


A translator must provide: function_decl (using mi_scene_link), parameter_size (as mi_scene- 
create argument), result_size, parameters. 

A translator may provide: next_function, interfacephen, ghost_offs, no_expl_params, 
label. 
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Functions are shading functions are pairs of a function identification (the shader name) and a 
parameter block. They are used for materials, textures, lights, transformations, and many other 
purposes. Most are called during rendering; some are called during preprocessing or tessellation. 
user?! cached_address*'!, cached_result*:! 
and lock>:! all assumed that preprocessing or shaders could write to the scene DAG, which is not 
the case in mental ray 3.0 so these fields were retired. The only field of interest to shaders was 
user, which could be used to store shader user data, typically in init shaders. New shaders must 
use mi_query in miQ_FUNC_USERPTR mode to access the user pointer. 


type is one of the miFUNCTION_* values. Note that some types such as miFUNCTION_OUTFILE do 
not actually describe procedural functions; using a miFunction here allows convenient chaining 
of output statements or pass statements®'! in the camera. 


out_typemap is a bitmap that contains the image types needed for the function if it is either an 


output shader or an output file. In the future, this will also be used for pass functions*"'. 


out_interpmap is a bitmap that contains the interpolation flags for each bit in the out_typemap 
bitmap. 


function_decl is the declaration of the function, containing both the shader name and a declaration 
of the parameters it requires. Declaration database elements have type miSCENE_FUNCTION_ 
DECL; see below. miFunctions that do not have procedural functions, such as type miFUNCTION_ 
OUTFILE, have a null tag here. 


next_function references the next function in a chain. Some shader types allow chaining; for 
example there may be multiple lens shaders anchored in the camera that are called in sequence. 


parameter_indirect contains the tag of the shader where the parameters should be picked up. 
It is possible to put a parameterless shadow shader and/or photon shader into a material, that 
will use the parameters of the material shaders. This avoids redundant parameter lists but creates 
interdependencies, so it is rarely used. 


interfacephen is the tag of the phenomenon that contains the shader. Presently only used 
internally to cache the phenomenon tag for lens shaders required by a phenomenon. Should 
not be used by translators. 


parameter-size is the size of the shader parameter area in bytes. Shader parameters are stored at 
the beginning of the parameters array. 


result_size is the number of bytes in the result data structure. By default this is 16 (the size of 
miColor, which is the default return type). It must be set to match the result_size field of the 
declaration. In mental ray 3.0, it is important to set this field correctly for contour store shaders; 
this was unnecessary in mental ray 2.1. 


ghost_offs is nonzero for phenomenon miFunctions and provides an offset into the parameters 
array where the tags begin. This value is either zero or the smallest multiple of 4 equal to or 
ereater than parameter_size because tags are integers that must be properly aligned. 


, cached_ghost_ptr', gcache_timestamp~", lightlist* 


1 


> 
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pass_read>'! is the tag of a string (type miSCENE_STRING) for pass prep functions attached to the 
pass chain of the camera; or the tag of a tag list (type miSCENE_TAG) containing string tags followed 
by a null tag, for pass merge functions. The strings are pass file names. Non-pass functions do 
not use this field. 


pass_write>:! is the tag of a string (type miSCENE_STRING) for pass save, pass prep, and pass delete 
functions attached to the pass chain of the camera. The strings is a pass file name. Non-pass 
functions do not use this field. 


pass_maxsamples?'! is the max sampling density for the written pass file. The default is 6, which 
uses the rendering max sampling value from the options. This field is not currently used. 


no_expl_params is set if the function has no parameters, and should pick up the parameters from 
parameter_indirect. 


cloned is an internal flag used by mental ray to identify functions that were created during 
preprocessing to construct new shader chains from Phenomenon roots, for example if a 
Phenomenon adds a lens shader to the camera lens shader list. 


label is a number in the range 0... 255 that helps distinguishing shaders. A new number is assigned 
automatically whenever a new function is created, but no attempt is made to keep the numbers 
unique. This helps the incremental rendering heuristics to decide whether a pixel should be 
re-rendered. 


parameters contains one or two variable-sized data areas: the function parameters, and the 
optional tag ghost array. A pointer to the parameter block is passed to the shader whenever it is 
called. The parameters are expected to be laid out as described by the function declaration. 


The tag ghost array is used for phenomenon miFunctions. It exists only if ghost_offs is nonzero. 
It has the same layout as the parameter array, such that there is one tag for every parameter at the 
same offset in the respective array. If the tag for a parameter is nonzero, the tag points to another 
miFunction which must be called (unless its cache is valid, in which case the previous result is 
re-used; see above) to provide the parameter instead of using the parameter directly. In this case 
the parameter in the parameter array is the offset into the result returned by the call. 


4.3.6 User Data 


Element type: miSCENE-USERDATA 


Data type: miUserdata 
Sizes: int parameter_size 
Defaults: all nulls 


typedef struct miUserdata { 


miTag data_decl; /* parameter declaration */ 
miTag next_data; /* next data block in list */ 
miUint label; /* user-defined label integer*/ 


int parameter_size; /* size of parameter block */ 
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short one; /* ==1, for byte order check */ 


short spare1l; /* not used */ 
int spare2; /* not used */ 
char parameters [8] ; /* parameter block */ 


} miUserdata; 


This element describes a user-definable opaque data block. The API supports setting up these 
blocks from literal data, from a file, or from shader-like declared parameters. The purpose is 
carrying user data to shaders that would be too large, contain nonstandard data types, or be 
repeated in too many places to make storing it as shader parameters feasible. Except in the 
shader-like parameter case, the data is not byte-swapped by mental ray when transported to 
another host; this becomes the responsibility of the data recipient. 


data_decl is the tag of the declaration of the parameters, if the user data block is defined with 
parameters. If it was defined with literal data or read from a file, this field is a null tag. 


next_data allows chaining of user data blocks, much like shaders can be chained. 
parameter_size is the number of bytes stored in this data block, beginning at parameters. The 
rest of the header leading up to the data is not included. Zero is allowed but not useful. mental 
ray warns if a data block is defined larger than 16 MB. 

one is set to 1 when the data block is defined, and when it was defined with parameters and has 
been imported and byte-swapped. Since literal and file user data blocks are not swapped, the data 
recipient must assume that non-byte data read from the user data block must be byte-swapped if 


one has the value 0x0100 instead of 1. 


parameters contains the user data. Although declared with only eight characters, it is allocated 
smaller or larger depending on the user data block size such that it holds parameter_size bytes. 


4.3.7. Function Declarations 


Element type: miSCENE-FUNCTION_DECL 


Data type: miFunction_decl 
Sizes: int decl_size 
Defaults: all nulls, type miFUNCTION_C 


typedef enum { 
miTYPE_BOOLEAN = 0, /* simple types: used for */ 
miTYPE_INTEGER, /* returns and parameters */ 
miTYPE_SCALAR, 
miTYPE_STRING, 
miTYPE_COLOR, 
miTYPE_VECTOR, 
miTYPE_TRANSFORM, 
miTYPE_SHADER, /* complex types: used for */ 
miTYPE_SCALAR_TEX, /* parameters only */ 
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miTYPE_COLOR_TEX, 
miTYPE_VECTOR_TEX , 
miTYPE_LIGHT, 
miTYPE_STRUCT, 
miTYPE_ARRAY, 

mi TYPE. TEs, 
miTYPE_MATERIAL, 
miTYPE_GEOMETRY , 
miTYPE_LIGHTPROFILE, 
miTYPE_DATA, 
miTYPE_SPECTRUM, 


miNTYPES 
} miParam_type; 


typedef struct miPhen_decl { 


int n_subtags; 

miTag root; 

miTag lens; 

miTag output ; 

miTag volume; 

miTag environment ; 
miTag geometry ; 

miTag contour_store; 
miTag contour_contrast ; 
int lens_segnr ; 

int output_seqnr ; 

int volume_seqnr ; 

int environment_segnr ; 


/* 


/* 
/* 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


phenomenon types */ 


free-form user data */ 
light spectrum as args */ 


# of subshader/mtl tags */ 
root attachment point */ 
optional lens shaders */ 
optional output shaders */ 
optional volume shaders */ 
optional environm. shaders*/ 
optional geometry shaders */ 
opt’1 contour store func */ 
opt’1 contour contrast f. */ 
opt’1 sequence number */ 
opt’1 sequence number */ 
opt’1 sequence number */ 
opt’1 sequence number */ 


/* Fuzzy booleans (0=dont care, 1=false, 2=true) */ 


/* 
/* 


need scanline? */ 
need ray tracing? */ 


/* Normal Booleans (these cannot be set explicitly off): */ 


miCBoolean scanline; 
miCBoolean trace; 
miCBoolean derivi; 
miCBoolean deriv2; 
miUchar mintextures; 
miUchar minbumps ; 
miUchar volume_level; 
miUchar parallel; 
char shadow; 

char face; 

char render_space; 
miCBoolean cloned; 


} miPhen_decl; 


typedef struct miFunction_decl { 


miPointer 


sparep [2] ; 


enum miFunction_type type; 


declaration_size; 
result_size; 


miParam_type ret_type; 
int 
int 
int version; 


/* 
/* 
/* 
f/* 
/* 
/* 
/* 
[* 
/* 
/* 


/* 
/* 
/* 
/* 
/* 


need first derivatives? */ 
need second derivatives? */ 
not used */ 

not used */ 

optional volume level */ 
parallel output shader */ 

0, 1,7" Bert... *s* pean: */ 
‘f*rent. *hiack, ’a'li */ 
>c’amera, ’o’bject, O any */ 
delete decl when del. shd */ 


C function or phenomenon */ 
return type of shader */ 
size of declaration */ 

size of result struct */ 
shader version from .mi */ 
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miUint apply; /* what can it be used for? */ 
miPhen_decl phen; /* if type==miFUNCTION_PHEN */ 
int spare [2]; /* not used */ 

miTag defaults; /*x default values or 0 */ 

char name [miNAMESIZE] ; /* ascii name */ 

char declaration[4] ; /* declaration string */ 


} miFunction_decl; 


#define miDECL_SUBTAG(d,i) (...) 


A translator must provide: name, result_size, declaration, version. 
A translator may provide: type, ret_type. 
Provided by mi_scene_create: parameter_size, declaration_size, parallel, apply. 


lock*:! is a lock shared by all instances of a shader. 


type is one of miFUNCTION_C (shader), miFUNCTION_PHEN (Phenomenon), miFUNCTION_OUTFILE 
(output file, not a shader), or miFUNCTION_DATA (declaration of a user data block, not a shader). 


ret_type is the return type of the function. For backwards compatibility, undefined return types 
default to miTYPE_COLOR. The type is important for subshaders in shader trees. Only “simple 
types” are allowed here. 


name is an ASCII string identifying the shader. This name will be looked up in LINK’s symbol 


table at runtime. 


parameter-_size helps the translator decide how many bytes to allocate when a new miFunction 
entry is allocated, see above. The parameter size does not include space needed for parameter 
arrays. 


declaration_size is the size of the declaration array in bytes, including the trailing null byte. 


result_size is the number of bytes in the result data structure. By default this is 16 (the size of 
miColor, which is the default return type). It must be set to match the result_size field of the 
declaration. 


version is the declaration version. It can be queried by the shader using mi_query and allows the 
shader to ensure that the declaration and the shader agree. Also, if a shader library contains a 
function named shadername_version, it is scaled and its returned integer value must match the 
version. It is highly recommended to use this feature. 


apply is a bitmap that specifies what the shader can be used for. Each bit stands for a specific type 
of shader: 
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miAPPLY_LENS 
miAPPLY_ MATERIAL 
miAPPLY_LIGHT 
miAPPLY_SHADOW 
miAPPLY_ENVIRONMENT 
miAPPLY_VOLUME 
miAPPLY_TEXTURE 


lens shader in a camera 

material shader in a material 

light shader 

shadow shader in a material 

environment shader in a material or camera 
volume shader in a material or camera 
texture shader 


miAPPLY PHOTON photon shader in a material 
miAPPLY_GEOMETRY geometry shader 
miAPPLY DISPLACE displacement shader in a material 


miAPPLY_PHOTON_EMITTER 
miAPPLY_OUTPUT 
miAPPLY_LIGHTMAP?* 
miAPPLY_PHOTONVOL?:! 
miAPPLY_STATE>” 
miAPPLY_CONTOUR?>* 
miAPPLY_OTHER?>* 


photon emitter shader in a light 

output shader in a camera 

light map shader in a material 

photon volume shader 

state shader 

contour shader 

general-purpose shader, such as base shader 
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If the apply bitmap is zero (the default), it is not known what the shader can be used for, and all 
uses are legal. mental ray does not currently enforce non-applicability, this is only a hint. 


phen is a substructure containing fields used if the type is miFUNCTION_PHEN. The miPhen_decl 
substructure is still under development. Note that phenomena keep a list of tags of shaders, 
materials, lights, and other sub-objects defined in the scope of the phenomenon in a tag list that 
follows the declaration string. Tags in this list can be accessed with the miDECL_SUBTAG macro. 


defaults*’, if nonzero, contains the numerical default shader parameters for this shader. This 
is simply a tag of a miFunction whose parameters are copied to any new shader miFunction 
derived from this declaration. Only numerical values but not tags or arrays or array members 
may have defaults. 


declaration describes the parameter layout required by the shader. It is a sequence of ascii 
characters, each describing a type or structure; the sequence is an abbreviated form of the 
declaration syntax in the .mi file. The declaration is a list of return and parameter declarations. 
Each list item begins with an optional ’a’ for array, followed by the type (one of biscvtSCV1S$ 
for boolean, integer, scalar, color, vector, transform, scalar texture, color texture, vector texture, 
light, shader, and string) followed by a double-quoted name. Substructures are defined with 
{"name" followed by the structure name followed by the structure definition followed by }. The 
declaration has two parts separated by an equals sign; the first part declares the return type and 
the second part declares the parameters. The first part may have only one field that may not be 
an array and whose double-quoted name part is omitted, but it may be a structure containing 
named fields. One null byte terminates the entire declaration. 


For example, a shader returning a color r and accepting three parameters, a scalar s, an array 
of structures t containing two integers 7/1 and 72, followed by a light array / would lead to the 


following declaration string: 


rr far fark as ae lai ¥ Maes Pg 2 8 ae 
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If the return type were a structure containing a color c and a boolean J, the declaration changes 
to: 


fete tbe" aay" as PEPE eT he" ae 
4.3.8 Boxes 


Element type: miSCENE-NBOX 


Data type: miBox 
Sizes: 
Defaults: all nulls 


typedef struct miBox { 


miCBoolean mtl_is_label; 

miUchar sharp; 

miUchar spare [2] ; 

miUint spare2; 

miVector bbox_min; /* bounding box: low corner */ 

miVector bbox_max; /* bounding box: high corner */ 

miUint no_primlists; /* number of lists of prims, 
excluding border primlists */ 

miUint no_prims ; /* total number of primitives 
contained in all primitive lists, 
excluding border prims */ 

miUint no_border_primlists; /* number of border primlists */ 

miUint no_border_prims;/* number of primitives contained */ 

/* in all border primlists */ 

miUint primdata_size; /* prim data: size per primitive */ 

miUint pdata_size; /* prim data: total size (there could 
be extra data after primlist data */ 

miTag topology; /* adjacency information for all 
primitives (regiont+border) */ 

miUint prim_offset; /* byte offset: primitives */ 

miUint mtl_offset; /* byte offset: materials */ 

miUint dim_offset; /* byte offset: tex/usr offset table*/ 

miUint pdata_offset; /* byte offset: prim data */ 

miVertex_info vertex_info; /* vertex specification */ 

miScalar datalij: /* vertex lines begin, more follow */ 

} miBox; 


In mental ray 3.4, miBox was introduced to improve efficiency. miBox optimizes memory 
coherence. 


A translator should not change the fields in an miBox directly; the api functions mi_api_ 
primlist_begin, mi-apiprimlist_border, mi_api_primlist_dimensions, mi_api_primlist_approx, mi- 
api_primlist_topology, mi_api-primlist_end should be used. Writing boxes directly makes rendering 
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faster because no tessellation is involved, but it does make the code more susceptible to changes 
in mental ray. miBox is an internal data structure that changes in incompatible ways periodically, 
unlike miObjects. 


mtl_is_label is a flag that informs the renderer that the material field in the primitives does not 
hold a material but an integer label. The renderer must ignore the material in this case and use the 
inherited material. This flag is set for tagged objects in the mi2 language. 


sharp stores the tessellation sharpness: 0 means interpolated and 255 means faceted. mental ray 
3.2 also allows intermediate values in the range 1..254. 


bbox_min and bbox_max are the low and high corners respectively of the bounding box around 
the vextex positions. 


no_prims is the total number of primitives (triangles, strip faces, quads etc) contained in all 
primitive lists, excluding border primitives. 


no_primlists is the total number of primitive lists contained in the box. Each primitive list consists 
of prims, excluding border primitives. 


no_border_prims is the total number of primitives in all border primitive lists. 
no_border_primlists is the number of primitive lists defining the border. 


primdata_size specifies the number of 32-bit integers which are assigned to each primitive from 
the pdata_offset array. For example primdata_size = 1 means that for subsequent primitives one 
integer from pdata_offset can be used as user data. 


pdata_size specifies the size of the whole pdata section. There may be extra space after primlist 
data, for individual needs. 


prim_offset is the offset to an array of integers defining multiple primitive lists. Each primitive 
list begins with a primitive type combined with a count into a single 32-bit value: type is stored 
in bits 28-31, count in bits 0-27. The primitive vertex integers follow, referring to the vertex lines. 


mtl_offset is the offset to an array of integers defining materials. 


dim_offset is the offset to the array of scalar offsets within a vertex line for all texture and user 
spaces. The dim_offset array has at least one entry for texture spaces and one for user data spaces, 
which are identical to no_textures or no_users. If no_textures or no_users is greater than zero, 
additional entries are present with values of at least three (defined after position in the vertex 
line). 


pdata_offset is the offset to the user data, swapped as integers. Interpretation is up to the 
application. 


data[1] is the beginning of the vertex line storage. 
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vertex_info defines a primitive vertex. Vertex data is stored as an interleaved array of lines of 
scalars in the box. A line contains a 3-d vertex position and may contain, for example, a normal 
(3 scalars), first derivatives (6 scalars), second derivatives (9 scalars), textures, and user data. 
miVertex_info describes the layout of the lines. 


typedef struct miVertex_info { 


miUint2 line_size; /* vertex line size in #scalars */ 
miUchar normal_offset; /* when 0, not present */ 

miUchar derivs_offset; /* surf derivs, when 0, not present */ 
miUchar derivs2_offset; /* surf 2nd derivs, when 0, not pr. */ 
miUchar bump_offset; /* bump basis vectors if non null */ 
miUchar no_bumps ; /* number of bump vectors */ 

miUchar motion_offset; /* when 0, not present */ 

miUchar no_motions; /* number of motion vectors */ 

miUchar texture_offset; /* when 0, not present */ 

miUchar no_textures; /* number of textures */ 

miUchar user_offset; /* when 0, not present */ 

miUchar no_users; /* number of user vectors */ 

miUchar spare [3] } /* not used */ 


} miVertex_info} 


line_size is the number of scalars in a line of vertex data. 
normal_offset is the to the normal vector. 

derivs_offset is the offset to the first partial derivatives. 
derivs2_offset is the offset to the second partial derivatives. 
bump-offset is the offset to the bump vectors. 
no_bumps is the number of bump vectors. 
motion_offset is the offset to the motion vectors. 
no_motions is the number of motion vectors. 
texture_offset is the offset to the texture vectors. 
no_textures is the number of texture spaces. 
user_offset is the offset to the user vectors. 


no_users is the number of user spaces. 
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A number of macros exist to provide access to miBox contents. 


e Access within a section 
miBOX_VERTEX_LINES(box) returns the address of the first vertex line. 
miBOX_VERTEX_LINE(box, idx) returns the address of a certain vertex line. 
miBOX_PRIMS(box) returns the address of the first primitive list. 
miBOX_MATERIALS(box) returns the address of the first material tag/integer. 
miBOX_TEX_OFFSET(box) returns the address of the first texture space dim_offset entry. 
miBOX_USER_OFFSET(box) returns the address of the first user space dim_offset entry. 
miBOX_PRIMDATA (box) returns the address of the first 32-bit data for primitives. 


e Access within a line 
miVL_POS(box, line) returns the vertex position. 
miVL_NORMAL (box, line) returns the vertex normal. 
miVL_DERIVS1(box, line) returns the partial derivative u vector, v at subsequent address. 
miVL_DERIVS2(box, line) returns the second derivatives (three vectors in total). 
miVL_BUMP(box, line) returns the first bump basis vector. 
miVL_MOTION (box, line) returns the first motion vector. 
miVL_TEXTURE(box, line) returns the first texture scalar. 
miVL_TEXTURE_D(box, line, offs returns the address of a certain texture space. offs is 


an entry from the dim_offset array, i.e. a scalar offset within the line. 
miVL_USER(box, line) returns the first user vertex data. 
miVL_USER_D(box, line, offs) returns the address of a certain user data space. offs is an 
entry from the dim_offset array, i.e a scalar offset within the line. 

e Number of items 
miBOX_NO_VTXLINES(box) returns the number of vertex lines. 
miBOX_NO_MATERIALS(box) returns the number of materials defined. 


e Primitive data 
miBOX_PD(box, idx) return the address of primitive data for the primitive with global 
index idx. 

e Other 
miBOX_POS(box, idx) returns the position entry for line index idx. 
miBOX_MOTION (box, idx, which) returns the motion vector which for line index idx. 


miBOX_TRI(box, idx) returns vertex triple for a certain triangle. Assumes that the box 
defines one sequential list of triangles. Skip the primtype/index count entry (+1). 


miBOX MATERIAL(box, idx) returns material for a certain triangle, same assumptions 
as for miBOX_TRI. 


miBOX_SIZE(box) returns the size of the entire miBox. 
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4.3.9 Objects 


Element type: miSCENE_-OBJECT 


Data type: miObject 
Sizes: — 
Defaults: as described below 


enum mi0bject_type { 
miQBJECT_POLYGONS, 
miOBJECT_FACES , 
miQBJECT_BOXES , 
miQBJECT_SPACECURVES , 
miQBJECT_SUBDIVSURFS , 


miQBJECT_ALGEBRAICS, /* for future use */ 
miQBJECT_PLACEHOLDER , /* read geometry on demand */ 
miOBJECT_HAIR 

}; 

typedef struct miObject { 
int spare_0[3]; /* not used */ 
miUint volume_id; /* autovolume identification */ 
miTag finalgather_file; /* fgmap file name, if any */ 
enum mi0bject_type type; /* which in union to use */ 
miUinti visible; /* object visible? * / 
miUinti shadow; /* cast a shadow? * / 
miUint1 reflection; /* bitO=cast, biti=receive * / 
miUinti refraction; /* bitO=cast, biti=receive * / 
miUint1i transparency ; /* bitO=cast, bitli=receive */ 
miUint1 caustic; /* bitO=cast, biti=receive * / 
miUint1 globillun; /* bitO=cast, biti=receive * / 
miUinti finalgather; /* bitO=cast, biti=receive * / 
miUint1 select; /* selectable when picking? */ 
char face; /* a=all, f=front, b=back * / 
miUint1 spare_1[5]; /* not used * / 
miCBoolean fine; /* API: has "fine" miApprox */ 
miBoolean view_dependent; /* miQBJECT_FACES only * / 
miBoolean mtl_is_label; /* poly/surf mtls are labels */ 
miScalar maxdisplace; /* max return of displ shader*/ 
miBoolean hardware; /* use hardware shading */ 
miTag userdata; /* optional user data blocks */ 
miUint label; /* optional label * / 
miVector bbox_min; /* bounding box: low corner */ 
miVector bbox_max; /* bounding box: high corner */ 
miVector bbox_min_m; /* bbox shift at T==1.0 (low) */ 
miVector bbox_max_m; /* bbox shift at T==1.0 (hi) */ 
miTag functions; /* SCENE: material req list */ 
unsigned int n_functions; /* SCENE: # tags in functions*/ 
miCBoolean mbox_explicit; /* motion box given by user */ 
miSint1 min_samples; /* per-object oversampling, */ 
miSint1 max_samples; /* defaults -128 and 127 * / 
miUchar spare_3[4]; /* not used * / 
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miUinti shadowmap ; /* casts shadowmap shadows? */ 
miScalar ray_offset; /* ray offset for the object */ 
miTag approx_list; /* list of miApproximations */ 
union { 

miPolygon_list polygon_list; 

miFace_list face_list; 

miTag box_list; 


miSpacecurve_list spacecurve_list; 
miSubdivsurf_list subdivsurf_list; 
miPlaceholder_list placeholder_list; 
miHair_list pats List: 
} geo; /* geometry * / 
} miObject; 


typedef struct miPolygon_list { 


miGeoIndex no_polygons ; 

miGeoIndex no_indices; 

miGeoIndex no_vertices; 

miGeoVector_list vect_info; /* contents of vector array */ 
miVertex_content vert_info; /* vertex size & content */ 
miTag polygons ; /* array of miPolygon */ 

miTag indices; /* array of miGeoIndex */ 
miTag vertices; /* see vert_info */ 

miTag vectors; /* array of miGeoVector */ 
miApprox approx; /* poly approx technique */ 


} miPolygon_list; 


typedef struct miFace_list { 


miGeoIndex no_faces; 

miGeoIndex no_surfaces; 

miGeoIndex no_curves; 

miGeoIndex no_specpnts; 

miGeoIndex no_surf_scalars; 

miGeoIndex no_curve_scalars; 

miTag faces; /* array of miFace */ 
miTag surfaces; /* array of miSurface */ 
miTag curves; /* array of miCurve */ 
miTag specpnts; /* array of miCurve_point */ 
miTag surf_scalars; /* array of miGeoScalar */ 
miTag curve_scalars; /* array of miGeoScalar */ 
miTag basis_list; /* miBasis_list */ 


} miFace_list; 


typedef struct miSpacecurve_list { 


miGeoIndex no_spacecurves ; 

miGeoIndex no_curves; 

miGeoIndex no_specpnts; 

miGeoIndex no_curve_scalars; 

miTag spacecurves ; /* array of miSpacecurve */ 
mitag curves; /* array of miCurve */ 
miTag specpnts; /* array of miCurve_point */ 
miTag curve_scalars; /* array of miGeoScalar */ 


miTag basislist; /* miBasis_list */ 
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miBoolean pad; /* not used */ 
} miSpacecurve_list; 


typedef struct miSubdivsurf_list { 
miGeoIndex no_subdivsurfs; 
miTag subdivsurfs; 

} miSubdivsurf_list; 


typedef struct miPlaceholder_list { 


miTag object; /* the real object with geom.*/ 
miTag filename; /* file name to read */ 
enum mi0bject_type type; /* type of object created */ 


} miPlaceholder_list; 


typedef struct miHair_list { 


miGeoIndex no_hairs; /* number of hairs */ 
miGeoIndex no_scalars; /* number of vectors */ 
miHair_content hair_info; /* data attached to hairs */ 
miHair_content vert_info; /* data attached to vertices,*/ 
/* bump vars used for radius */ 
miTag hairs; /* 1st hair vec: milInteger[] */ 
miTag scalars; /* control points: miScalar[]*/ 
milnteger approx; /* quality control of approx */ 
miTag material; /* material for all hairs */ 
miScalar radius; /* hair radius, default 1 */ 
int degree; /* Bezier degree 1..3, def. 1*/ 
int space_max_size; /* space subdiv. leaf size */ 
int space_max_depth; /* space subdiv. tree depth */ 


} miHair_list; 


A translator must provide: type, fine, geo. 


volume-_id assigns a volume identification to the object. It allows combining separate objects into 
a logical group which is treated as a single object for inside-outside computation in autovolume. 


finalgather_file °-* file (list) argument allows a file name or a list of file names with finalgather 
map(s) to be specified to be used for the object. If identical file names or file name lists are used 
for several objects, only one copy of finalgather map will be kept in memory. 


type (default miOBJECT_POLYGONS) specifies the type of the geometry attached to this object. It 
may be one of miOBJECT_POLYGONS, miOBJECT_FACES, mi0BJECT_BOXES, miOBJECT_SUBDIVSURF, 
miOBJECT_PLACEHOLDER>*, or miOBJECT_HAIR>!. This field determines which member of the 
union is used. Algebraics are not supported. 


visible is, as of mental ray 3.4, a bitmap flag. Bit 0 controls whether the object is visible. The 
remaining bits are unused. 


shadow flag is a bitmap that controls casting and receiving of shadows separately. Bit 0 enables 
shadows cast from this surface, and bit 1 allow shadows to be received by (fall onto) this object. 
By default, bit 0 is 0 and bit 1 is 1 (mode 2). 
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reflection’* refraction’* and finalgather’* flags replace the trace flag. Code that writes to the 
trace field must now write to these three flag bitmaps instead. Again, bit 0 enables casting and 
bit 1 enables receiving, and the defaults are 0 and 1, respectively (mode 2). 


transparency’™ flag that enables visibility of the surface to transparency rays, again separately 
for casting (bit 0) and receiving (bit 1). Unlike the other flags, both bits are on (mode 3) by default 
to ensure backwards compatibility. 


caustic is a bitmap with three valid bits. Bit 0, if set, enables generation of caustics cast by this 
object. Bit 1, if set, enables receiving caustics. Bit 4, if set, makes this object invisible to caustic 
photons. 


globillum is a bitmap with three valid bits. Bit 0, if set, enables generation of global illumination 
from this object. Bit 1, if set, enables receiving of global illumination by this object. Bit 4, if set, 
makes this object invisible to global illumination photons. 


select’ (default miFALSE) makes the object subject to select tracing. 


visible, shadow, caustic, globillum, and select*>* flags are inherited in the scene DAG. See 
page 504 for an explanation of the inheritance. 


face’* controls face culling. The possible values are ’£’ (front), ’b’ (back), and ’a’ (all). If not 
specified, the culling flag given in the options or in the state is used. 


fine’! must be set if the object contains any approximation with the fine*' flag set. It is set 
automatically by API. This field is redundant but allows mental ray to detect very quickly 
whether the object needs special treatment without scanning its contents. 


view_dependent (default miFALSE) enables view-dependent tessellation if the object has type 
miOBJECT_FACES. It should be set to miTRUE iff any of the surfaces in the object references a view- 
dependent approximation. It should not be changed between preprocessing and postprocessing. 


mtl_is_label is a flag that informs the renderer that the material field in the polygons or surfaces 
does not hold a material but an integer label. The renderer must ignore the material in this case 
and use the inherited material. This flag is set for tagged objects in the mi2 language. 


maxdisplace** specifies the maximum allowed displacement applied to object control points in 
local object space in normal direction. 


userdata allows attaching a user data block (miUserdata) or a chain of user data blocks. Shaders 
can retrieve the data with mi_query. 


label is a 32-bit integer that may be used to identify the object in shaders. mental ray does not 
use it In any way. 


i koe 


bbox_min’* and bbox_max’* are a bounding box that encloses all triangles resulting from 
tessellating this object, without taking motion blur or displacement into account. For polygons 
this is the convex hull of all point-in-space vectors, but for other object types better bounding 
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boxes should be found to make rendering more efficient. 
bbox_min_m°* and bbox_max_m°™ are a bounding box of all motion vectors, if there are any. 
bbox_min_m is composed of all the smallest X, Y, and Z components of all motion vectors, 
and bbox_max_m is composed of all the greatest components. If setting these fields, set mbox_ 
explicit?! to miTRUE. 


functions if this is not a null tag, it points to a list of material tags. This list represents the required 
materials for the object. 


n_functions the number of tags in the functions taglist. 
mbox_explicit’:' specifies that the bbox_min_m and bbox_max_m were specified by the user, and 
do not represent defaults computed by mental ray. 


min_samples°! specifies that this object should be oversampled no less than this value. The 
default is -128, which makes the object default to the minimum sampling value in the options. 


max-_samples>'' specifies that this object should be oversampled no more than this value. The 
default is 127, which makes the object default to the maximum sampling value in the options. 


shadowmap”” specifies that the object casts shadows into shadowmaps, if the shadow flag is 
enabled as well. 

ray_offset’” specifies the distance from the surface where secondary rays start. Effectively, no 
intersections closer than this distance will be found. This is useful to prevent rays leaving a 
visible-only high-resolution surface hitting the low-resolution trace-only version of the same 
surface. Different versions can be constructed with object or instance flags, or with flagged 
approximations. 


approx _list>? 


is the list with ten approximations inherited from the instance. 

geo is a union containing type-specific data. The suffix “_list” indicates that several types store 
the actual geometry in one or more lists of specific types; these lists are anchored here. The 
box_list case is a tag of a database element of type miSCENE_BOX. The box data type has been 
described above. Polygonal geometry is stored in four lists, all anchored in the geo. polygon_ 
list structure. 


The following diagram shows the connections between the four lists: 
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miGeolndex miGeolndex 


miPolygon (indices) (vertices) miGeoVector 


vect_info.no_points 


vect_info.no_normals 


: 


vect_info.no_motions 


vect_info.no_textures + 
vect_info.no_bumps 


vect_info.no_users 


| vert_info.sizeof_vertex 


Polygonal Geometry Storage 


Arrows indicate indices into the pointed-to data structure. All four grey boxes are separate 
Scene database element types, refer to the sections for miSCENE_POLYGON, miSCENE_GEOINDEX, 
and miSCENE_GEOVECTOR, respectively. The data structures are similar to the box data structure, 
except that the lists are stored in separate database elements, and that an index list is inserted that 
allows storing polygons with different numbers of vertices in a miPolygon data structure that 
has a constant size. The polygon points to the first vertex index in the index list and gives the 
number of vertices, as opposed to triangles in boxes that contain the three vertex indices directly. 


geo.polygon_list.no_polygons is the number of polygons in the polygons list. 
geo.polygon_list.no_indices is the number of indices in the indices list. 


geo.polygon_list.no_vertices is the number of vertices in the vertices list. Each vertex consists of 
vert_info.sizeof_vertex indices. 


geo.polygon_list.vect_info describes the sections of the vector list. For details, see the section for 
boxes above. 
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geo.polygon_list.vert_info describes the layout of the indices in the vertex list. For details, see 
the section for boxes above. 


geo.polygon_list.polygons is the tag of the polygon list. 
geo.polygon_list.indices is the tag of the index list. 
geo.polygon_list.vertices is the tag of the vertex list. 
geo.polygon_list.vectors is the tag of the vector list. 


geo.polygon_list.approx is the approximation technique for displacement-mapped polygons. (It 
does not apply to polygons whose material does not specify displacement maps.) 


Surface geometry is more complex. It is stored in up to seven different database elements, all 
of which are anchored in geo.face_list. The term face describes one complete visible free-form 
surface, which is built from one geometry surface and multiple optional texture surfaces, bump 
surfaces, and/or motion surfaces that provide certain types of mappings on the surface. For details 
on texture surfaces, refer to the mental ray User Manual. Unlike polygons, surfaces store their 
parameter lists and vectors in large miGeoScalar lists. This simplifies storing one, two, three, 
and four dimensional data in the same list. Trimming, hole, and special curves can optionally be 
attached to faces; they have their own scalar lists. Both surfaces and curves may reference optional 
special points. Every surface references two bases, and every curve references one base. Again, 
all lines in the following diagram indicate indices. 
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miFace miSurface miGeoScalar 
surface_idx 


Curvseg_idx 


miBasis_list 


basis_idx[0] 
ee > 
basis_idx[1] 
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' specpnt_idx 
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| 
| 
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miGeoScalar 


Free-form Surface Geometry Storage 


geo.face_list.no_faces is the number of faces in the geo.face_list.faces list. 
geo.face_list.no_surfaces is the number of surfaces in the geo.face list. surfaces list. 
geo.face_list.no_curves is the number of curves in the geo.face_list.curves list. 
geo.face_list.no_specpnts is the number of special points in the geo.face_list.specpnts list. 
geo.face_list.no_surf_scalars is the number of surface scalars in the geo.face_list.surf_scalars list. 
geo.face_list.no_curve_scalars is the number of curve scalars in the geo.face_list.curve_scalars list. 


geo.face_list.faces is the tag of the list of faces. 
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geo.face_list.surfaces is the tag of the list of surfaces. 
geo.face_list.curves is the tag of the list of curve. 
geo.face_list.specpnts is the tag of the list of special points. 


geo.face_list.surf_scalars is the tag of the list of surface scalars, which are used for parameter 
vectors, control points, weights etc. that define all surfaces in this object. 


geo.face_list.curve_scalars is the tag of the list of curve scalars, which are used for parameter 
vectors, control points, weights etc. that define all curves in this object. 


geo.face_list.basis_list is the tag of the list of all bases. 
An object of type miOBJECT_SPACECURVE contains a list of space curves. A single space curve 
consists of curve segments which are approximated as a single three dimensional curve. The 


approximation result is stored in a miLinebox. 


geo.spacecurve_list.no_spacecurves is the number of space curves in the geo.spacecurve- 
list.spacecurves list. 


geo.spacecurve_list.no_curves is the number of curves in the geo.spacecurve_list.curves list. 


geo.spacecurve_list.no_specpnts is the number of special points in the geo. spacecurve list. specpnts 
list. 


geo.spacecurve_list.no_curve_scalars is the number of curve scalars in the geo.spacecurve- 
list.curve_scalars list. 


geo.spacecurve_list.spacecurves is the tag of the list of spacecurves. 

geo.spacecurve_list.curves is the tag of the list of curves. 

geo.spacecurve_list.specpnts is the tag of the list of curve special points. 
geo.spacecurve_list.curve_scalars is the tag of the list of curve scalars. 
geo.spacecurve_list.basis_list is the tag of the list of all bases used by the curves. 

An object of type miOBJECT_PLACEHOLDER>* contains a reference to the actual object containing 
the geometry, which is created on demand. A placeholder object must have a bounding box, and 
motion bounding box and maximum displacement fields if applicable, and may contain only a 
single object group. 

geo.placeholder_list.object>* is the tag of the object that holds the actual geometry. This must 


be a demand-loaded tag, not a regular tag. The only way to construct such a tag is the mi_api- 
object_file function. Do not assign or access this field directly. 
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geo.placeholder_list.filename’* is the tag of a string containing the .mi scene file name that 


defines the object. This is only used for placeholder objects defined with mi_api_object_file. 
geo.placeholder_list.type’* is the myObject_type of the object whose place is being held. 


An object of type miOBJECT_HAIR>! defines an object with a different type of geometry that is 
not based on triangles but hairs. Since there is typically a very large number of hairs, this is far 
more efficient in terms of both memory usage and rendering performance. The description is 
very compact: 


miHair_list miScalar 
scalars 


hair texel 0 header of hair #1 


hair texel 1 
hair radius 


point coord x point #1 of hair #1 


point coord y 
point coord z 
point motion x 
point motion y 
milnteger : point motion z 
; point texel 0 
point #2 of hair #1 


hair #1 point coord x 


ee point coord y 


; point coord z 

hair end marker 5 point motion x 
: point motion y 
point motion z 
point texel 0 
header of hair #2 


hair texel 0 
hair texel 1 
hair radius 
point #1 of hair #2 


point coord x 
point coord y 
point coord z 
point motion x 
point motion y 
point motion z 
point texel 0 


point coord x point #2 of hair #2 


point coord y 

point coord z 

point motion x 

point motion y 

point motion z 

point texel 0 

point #3 of hair #2 


point coord x 
point coord y 

point coord z 

point motion x 
point motion y 
point motion z 
point texel 0 


Hair Geometry Storage 
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Hairs are stored in a scalar list. Each hair has some data that is shared by all points of that hair, 
and some data that is separate for each point of the hair. All hairs share the exact same layout, 
except that they may have different numbers of points. In this example, each hair has two texel 
scalars (U and V) and a radius; and each point has a coordinate (X, Y, and Z; mandatory), one 
motion vector (X, Y, Z), and one texel scalar (T). The hairs list contains indices into the scalar 
list where the corresponding hair begins, plus one extra hair end marker at the end. Here there 
are two hairs, one with two points and one with three. 


geo.hair_list.no_hairs?:! is the number of hairs, 2 in the example. There is always one more index 
in the hairs list for the end marker. Each index must be greater than the previous by 7 +) - 1, 
where 7 is the size of the header (3 in the example), 7 is the size of a point (7 in the example), and 
n is the number of points for this hair (2 and 3 in the example). API verifies this. 


geo.hair_list.no_scalars’:' is the number of scalars in the scalar list. 


geo.hair_list.hair_info’:' describes the size and layout of the hair headers in the scalar list. This 
structure and vert-info work like in objects and boxes (see page 524), but count scalars, not 
vectors. 


geo.hair_list.vert_info°'! describes the size and layout of the points in the scalar list. 
geo.hair_list.hairs®:' is the tag of a database element containing the index integers. 
geo.hair_list.scalars’:! is the tag of a database element containing the scalars. 


geo.hair_list.approx’'' specifies the number of linear segments used to approximate a curve 
segment. 
geo.hair_list.material>' is the material shader shared by all hairs. If this is a null tag, the material 
is inherited from the instance. 


geo.hair_list.radius*:! specifies the radius of all hairs, if neither hair_info nor vert_info specify 
radius values. 


geo.hair_list.degree:! is the degree of the Bézier curves that approximate the hair. It must be 1, 
2, or 3. Each hair is defined by degree - + 1 points, for some integer 7 > 0. The approximation 
will result in 2 - approx linear segments. 


geo.hair_list.space-max_size*' specifies the maximum leaf size of the hair BSP tree that is used 
for intersection testing. If left at 0, mental ray chooses a default. 


geo.hair_list.space.max_depth*! specifies the maximum depth of the hair BSP tree that is used 
for intersection testing. If left at 0, mental ray chooses a default. 
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There are two data structures that are used to describe the format of vertices and vectors: 


typedef struct miVertex_content { 


miUchar sizeof_vertex; /* size of a vertex */ 

miUchar normal_offset; /* when 0, not present */ 

miUchar motion_offset; /* when 0, not present */ 

miUchar derivs_offset; /* surf derivs, when 0, not present */ 
miUchar derivs2_offset; /* 2nd derivs, when 0, not present */ 
miUchar motion_offset; /* when 0, not present */ 

miUchar no_motions; /* number of motion vectors */ 
miUchar texture_offset; /* when 0, not present */ 

miUchar no_textures; /* number of textures */ 

miUchar bump_offset; /* when 0, not present */ 

miUchar no_bumps; /* number of bumps */ 

miUchar user_offset; /* when 0, not present */ 

miUchar no_users; /* number of user vectors */ 


} miVertex_content; 


A translator must provide: all fields. 

This structure is used to describe which information is stored with each vertex. It is also used to 
inform the tessellator what information to create vertices with. Vertices always consist of at least 
one vector reference for the point in space. The normal, the motion vectors, the surface derivative 
pair, the list of textures, the list of bump basis vectors, and the list of user vectors are all optional. 
Multiple motion vectors (up to 15 per vertex) are supported only in mental ray 3.1; mental ray 
3.0 has the no_motions field but ignores it when rendering; mental ray 2.1 lacks this field. 


A vertex is a list of indices into the actual vector table. Each such list begins with the index for 
the point in space, said to be at offset 0 in the list. The miVertex_content structure describes at 
which offset in the list other vector indices can be found. For example, if there is an index for a 
normal in the list directly after the index for the point in space, normal_offset would be 1. 


If some vertices have a certain type type of index and others do not (like some vertices have 
normals and others do not), the offset in the miVertex_content structure is nonzero but the 
index is set to miNULL_GEOINDEX in those vertices that do not need it. Using 0 for nonexistent 
offset members is ok because the first index in a vertex (which has offset 0) is the point in space, 
which must always exist. Do not confuse null offsets with null indices, which must use miNULL- 
GEOINDEX instead of 0 because the first vector in a polygon vector list can be something other 
than a point in space. Polygon lists mirror the order in the .mi file. 


The second recurring structure is the vector list header: 


typedef struct miGeoVector_list { 


miGeoIndex no_vectors; /* total number of input vectors */ 
miGeoIndex no_points; /* number of points in space */ 
miGeoIndex no_normals; /* number of normals */ 

miGeoIndex no_derivs; /* number of ist/2nd surface derivs */ 
miGeoIndex no_motions; /* number of motion vectors */ 
miGeoIndex no_textures; /* number of texture coordinates */ 


538 4 Geometry Shaders 


miGeoIndex no_bumps; /* number of bump basis vectors */ 
miGeoIndex no_users; /* number of user-defined vectors */ 
} miGeoVector_list; 


A translator must provide: all fields. 


All the vertex indices described by the miVertex_content structure are indices into the actual 
vector list. The vector list itself is partitioned in the eight “sections”: one for points in space, one 
for normals, one for surface derivatives, and so on. 


4.3.10 Approximations 


Element type: — 

Data type: miApprox 

Sizes: — 

Defaults: as set by mrAPPROX_DEFAULT() 


enum miApprox_method { 
miAPPROX_PARAMETRIC, 
miAPPROX_REGULAR, 
miAPPROX_SPATIAL, 
miAPPROX_CURVATURE, 
miAPPROX_LDA, 


miAPPROX_ADJACENCY , /* only for curves */ 
miAPPROX_ALGEBRAIC, /* only for surfaces */ 
miAPPROX_DEFTRIM, /* only for miFace def_trim_approx */ 
miAPPROX_REGULAR_PERCENT, /* new in 3.2, regular param nf4 m4 */ 


miAPPROX_INDIRECT, 
miAPPROX_NMETHODS 
rr 


enum miApprox_style { 
miAPPROX_STYLE_NONE, 
miAPPROX_STYLE_GRID, 
miAPPROX_STYLE_TREE, 
miAPPROX_STYLE_DELAUNAY , 
miAPPROX_STYLE_FINE, /* sub-object/subpixel tessellation */ 
miAPPROX_STYLE_FINE_NO_SMOOTHING,/* fine poly displacement without 
Hermite interpolation */ 
miAPPROX_NSTYLES 
}; 


#define miCNST_UPARAM 0 /* regular/parametric only */ 
#define miCNST_VPARAM 1 
#define miCNST_LENGTH 0 /* curvature/spatial only */ 
#define miCNST_DISTANCE i 

2 


#define miCNST_ANGLE 


4.3 Geometry Shader Data Structures 


enum miCnst_type { 


}; 

typedef struct miApprox { 
miScalar cnst [6] ; 
miUint1 sharp; 
miCBoolean spare; 
miCBoolean any ; 
miCBoolean view_dep; 
enum miApprox_method method; 
enum miApprox_style style; 
miUshort subdiv [2]; 
miGeoIndex max ; 
miScalar grading; 

} miApprox; 

#define miAPPROX_MAX_SUBDIV r 

#define miAPPROX_DEFAULT(A) do { 


miCNST_VISIBLE 
miCNST_TRACE, 
miCNST_SHADOW, 
miCNST_CAUSTIC, 
miCNST_GLOBILLUM, 
miCNST_NTYPES 


0, 


/* 


/* 


for accessing (int)cnst[0] */ 


must not be > 7 ! */ 


indexed with miUPARAM...miANGLE */ 
O=smooth normals, 255=faceted */ 
not used */ 

stop if any criterion is met */ 
view dependent? */ 


recursive subdivision depth */ 
maximum number of triangles */ 
min angle bound for graded meshing*/ 


\ 


(A) .style = miAPPROX_STYLE_TREE; \ 
(A) .method = miAPPROX_PARAMETRIC; \ 
(A) .sharp = 0; \ 
(A) .flag = miAPPROX_FLAG_ANY; X 
(A) .any = miFALSE; ." 
(A) .view_dep = miFALSE; \ 
(A) .cnst [0] = 0.0; \ 
(A) .cnst [1] = 0.0; \ 
(A) .cnst [2] = 0.0; \ 
(A) .cnst [3] = 0.0; \ 
(A) .cnst [4] = 0.0; \ 
(A) .cnst [5] = 0.0; \ 
(A).subdiv[miMIN] = 0; \ 
(A) .subdiv[miMAX] = 5; ‘ 
(A) .max = miHUGE_INT; \ 
(A) .grading = 0.0; } while (0) 
#define miAPPROX_FINE_DEFAULT(A) do { \ 
(A) .style = miAPPROX_STYLE_FINE; \ 
(A) .method = miAPPROX_LDA; \ 
(A) .sharp = 0; \ 
(A) .flag = (1<<miCNST_NTYPES)-1;\ 
(A) .any = miFALSE; \ 
(A) .view_dep = miTRUE; \ 
(A) .cnst [0] = 0.25; \ 
(A).cnst [1] = 0.0; ‘ 
(A) .cnst [2] = 0.0; \ 
(A) .cnst [3] = 0.0; \ 
(A) .cnst [4] = 0.0; \ 
(A) .cnst [5] = 0.0; \ 
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(A) .subdiv[miMIN] = 0; \ 
(A) .subdiv [miMAX] = miAPPROX_MAX_SUBDIV; \ 
(A) .max = miHUGE_INT; \ 
(A) .grading = 0.0; } while (0) 


A translator may provide: all fields. 


The approximation structure is a substructure of miPolygon_list, miCurve, and miSurface. It 
does not have its own database entry and no associated SCENE functions of its own. 


method is the approximation method, and must be one of miAPPROX_PARAMETRIC, miAPPROX_ 
REGULAR, miAPPROX_SPATIAL, miAPPROX_CURVATURE, miAPPROX_LDA, miAPPROX_ADJACENCY 
(available for curves only), and miAPPROX_REGULAR_PERCENT>’. The default is miAPPROX- 
PARAMETRIC. “LDA” stands for Length, Distance, Angle; this mode combines the spatial and 
curvature-dependent modes which are now considered obsolete. As a special case, the value of 
miAPPROX_INDIRECT°” switches the meaning of the cnst array to an array of six integer offsets 
into the inherited approximation list, which contains up to ten approximations separately for 
visible, trace, shadow, and other flagged approximations. 


tyle is the approximation style, and must be one of miAPPROX_NONE, miAPPROX_GRID, miAPPROX_ 
TREE, miAPPROX_STYLE_FINE>!, and miAPPROX_STYLE_FINE_NO_SMOOTHING?*Free mode is the 
default. The API and GAP module will automatically change the style field to grid mode if the 
method is parametric or regular. The fine approximation style’! only works with parametric 
and edge length criteria; the recommended mode is view-dependent edge length with a subpixel 
diagonal constant. If any approximation in an object uses fine approximation, the miObject should 
have the fine flag set. fine approximation, no smoothing can be used for polygon displacement 
for turning off a smoothing procedure which is used by default during fine polygon displacement. 
(See page 166 for more details about fine approximation.) 


sharp*' controls the normal vector interpolation. If set to 0, mental ray uses the interpolated 
normal as specified by the base surface, modified by displacement if available. If set to 255 (which 
corresponds to 1.0 in the .mi scene file), mental ray will use the geometric normal for a faceted 
look. This is primarily useful in miAPPROX_STYLE_FINE>:' mode. mental ray 3.2 also accepts values 
in the range 1..254 to blend smoothly between interpolated and faceted tessellations. 


any, if miTRUE, makes the tessellation stop if amy criterion is met, instead of when all criteria are 
met. Close faces are tessellated more finely than distant faces. This mode is not available for the 
parametric and regular method. 


view-dep, if mi TRUE, turns on view-dependent tessellation. Close faces are tessellated more finely 
than distant faces. This mode is not available for the parametric and regular method. 


cnst[O], cnst[1], and cnst[2] specify the approximation precision. They depend on the 
approximation method. The defaults are 1.0 (which is not ideal for curvature-dependent 
tessellation). The cnst array should be indexed using the miCNST_* constants. The cnst array 
was a miGeoScalar array up to mental ray 3.1, and switch to miScalar in mental ray 3.2. If the 
method field is miAPPROX_INDIRECT?”, these six cnst fields are interpreted as integer offsets into 
the inherited approximation list, which contains the actual approximations to use. Indirection 
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cannot be nested. For example, if the method is indirect, the approximation to use for shadow 
rays is inheritedlist [ (int)approx.cnst [ miCNST_SHADOW ]]. 


subdiv specifies the minimum and maximum number of subdivision recursion levels. 


grading is used for Delaunay tessellation only, and specifies how gradually the triangle mesh 
should become finer. 


cnst [0] cnst [1] cnsit(2 | 


number of U subdivs number of V subdivs 


parametric degree degree 


regular number of U subdivs number of V subdivs — 
spatial edge length limit 


curvature distance tolerance angle tolerance 


Ida edge length limit distance tolerance angle tolerance 


subdiv[0] and subdiv[1] specify the recursion limits. The defaults are 0 and 5, respectively. The 
maximum value is 7. A subdivision level 7 means that the curve, triangle, or surface is halved in 
each parameter direction 7 times, yielding on the order of 2” segments. The limits have no effect 
on Delaunay triangulation. 


max is used only for Delaunay triangulation. It specifies the maximum number of triangles to 
create. The number may be exceeded if the trimming and hole curves have too many vertices. 


4.3.11. Polygon Lists 


Element type: miSCENE-POLYGON 
Data type: miPolygonf | 

Sizes: int no_polys 

Defaults: all nulls 


typedef struct miPolygon { 


miGeoIndex no_loops; /* 1 + (number of holes) */ 

miGeoIndex no_vertices; /* total number of vertices + headers*/ 
miGeoIndex vertex_idx; /* into indices list, for sharing */ 
miTag material; /* surface properties */ 

miCBoolean convex; /* is polygon convex ? */ 

miCBoolean spare [3] ; /* not used */ 


} miPolygon; 
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A translator must provide: all fields except spare. 


no_loops is the number of loops of the polygon. Every polygon has exactly one outer boundary 
loop, plus any number of optional hole loops. Every loop is stored as a pseudo-index called a 
“header” that doesn’t actually refer to the vector list but gives the number of indices to follow, 
followed by that many indices. 


no_vertices is the total number of headers (the number of holes plus 1) plus the total number of 
vertices for this polygon. 


vertex_idx is an index to the first header of the polygon in the index list. mo_vertices indices 
beginning at vertex_idex define the polygon. 


material is the tag of the material of the polygon. It must refer to a database element of type 
miSCENE_MATERIAL. 


convex is a flag telling the tessellator that the polygon has no holes and is guaranteed to be 
convex. This saves time because GAP can use a very simple tessellation algorithm. 


4.3.12. Polygon Indices 


Element type: miSCENE-GEOINDEX 
Data type: miGeoIndex{ | 

Sizes: int no_indices 

Defaults: all nulls 


Polygon indices are simple miGeoIndex arrays. As described above, each polygon indexes a 
consecutive block of indices that describes one or more loops, each of which begins with a header 
pseudo-index giving the number of loop indices to follow. Each index indexes into the vertex list, 
after being multiplied by vert_info.sizeof_vertex. 


4.3.13, Polygon Vertices 


Element type; miSCENE-GEOVERTEX 
Data type: miGeoIndex[ ] 

Sizes: int no_indices 

Defaults: all nulls 


The vertex list is an miGeoIndex array. It works exactly like the vertex section of boxes; see above. 
The vert-info structure in miPolygon determines how many indices make up one vertex, and how 
it is laid out. Note that the no_indices argument of the create and resize functions is the number 
of indices, not the number of vertices. 
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4.3.14 Polygon Vectors 


Element type: miSCENE-GEOVECTOR 
Data type: miGeoVector[ | 

Sizes: int nO_vectors 

Defaults: all nulls 
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The vector list is amiGeoVector array. It is partitioned into sections as described by the vect_info 


structure in miPolygon. 


4.3.15 Surfaces: Face List 


Element type: miSCENE-FACE 
Data type: miFace[ ] 
Sizes: int no_faces 


Defaults: all nulls except where otherwise noted 


typedef struct miFace { 


miApprox def_trim_approx; 
miGeoRange range [miUV_DIM] ; 
miGeoIndex no_curves; 
miGeoIndex no_surfaces; 
miGeoIndex surface_idx; 
miGeoIndex curve_idx; 

miTag material; 


miVertex_content gap_vert_info; 
} miFace; 


A translator must provide: range, no_surfaces, surface_idx, material, gap_vert_info. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


approx techn. for default trims */ 
min/max for parameter vals*/ 

total number of curves */ 

total # of surfs: 1 geo. + xtras */ 
surface list index */ 

index into the ’curves’ list*/ 
optional: material of the face */ 
For calculating box sizes */ 


A translator may provide: def _trim_approx, no_curves, curve_idx. 


def_trim_approx is the approximation for default trimming curves. Default trimming curves are 
automatically created if the face has no explicit trimming curves attached. The default trimming 
curve follows the edges of the face. The miAPPROX_DEFTRIM approximation technique, which is 
allowed only here, should be used as default to create a default trim curve that does not introduce 


new vertices. 


range[miU] and range[miV] specify the minimum and maximum values of the U and V parameter 


vectors. 


no-_curves specifies the total number of curves used by this face. 


no-surfaces is the total number of surfaces for this face. This is at least 1 for the geometric surface, 
plus the numbers of texture, bump, and/or motion surfaces. 
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surface_idx is the index of the first surface in the surface list anchored in the object (see above) 
that is used for this face. This is the first of 20_surfaces consecutive surfaces to use. 


curve_idx is the index of the first curve in the curve list anchored in the object that is used for 
this face. This is the first of m0_curves consecutive curves to use. 


material specifies the tag of a material to use for the face. 


gap_vert_info describes the layout and size of the vertices to create during tessellation. The boxes 
created during tessellation will get a copy of this vertex info structure. 


4.3.16 Surfaces: Surface List 


Element type: miSCENE-SURFACE 


Data type: miSurface[ | 
Sizes: int no-_surfaces 
Defaults: all nulls, except where otherwise noted 


enum miSurface_type { 
miSURFACE_GEOMETRIC, 


miSURFACE_GEOMOTION, /* geometric + motion vectors */ 
miSURFACE_TEXTURE_2D, /* texture with/without seam compens */ 
miSURFACE_TEXTURE_3D, 
miSURFACE_BUMP, /* bump */ 
miSURFACE_TEXBUMP_2D, /* texture + bump */ 
miSURFACE_TEXBUMP_3D 

sj 

typedef struct miSurface { 
miApprox approx; /* approx techn. for surface */ 
miApprox disp_approx; /* approx for disp. surface */ 
miGeoIndex no_parms [miUV_DIM] ; /* no of parameter values */ 
miGeoIndex no_ctla: /* no of control points */ 
miGeoIndex no_specpnts; /* no of special points */ 
miGeoIndex scalar_idx; /* surf_scalar list index */ 
miGeoIndex specpnt_idx; /* special points list index */ 
miGeoIndex basis_idx[miUV_DIM] ; /* index into basis list */ 
enum miSurface_type type; 
miUshort degree [miUV_DIM] ; /* from bases, for GAP */ 
miUshort col dim: /* control pnt dimension */ 
miUshort spare [3]; 


} miSurface; 


A translator must provide: type, approx, disp_approx, ctl_dim, degree, no_parms, no_ctls, 
scalar_idx, basis_idx. 
A translator may provide: no_specpnts, specpnt_idx. 
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type must be one of the miSURFACE_ constants. The 2D variants perform seam rewind correction, 
the 3D variants do not. All surfaces begin with either miSURFACE_GEOMETRIC or miSURFACE_ 
GEOMOTION, optionally followed by one of the others for each texture space, beginning with space 
O up to a maximum of space 63. (Future versions may have a larger maximum, up to 255.) 


approx is the approximation technique as described above, in the miFace description. 


disp_approx is the approximation technique for the displaced surface, if a displacement shader is 
available. 


ctl_dim is the number of scalars per control point: 


miSURFACE_GEOMETRIC, non-rational: 3 
miSURFACE_GEOMETRIC, rational: 4 
miSURFACE_GEOMOTION, non-rational: 6 
miSURFACE_GEOMOTION, rational: 7 
miSURFACE_TEXTURE_2D 2 
miSURFACE_TEXTURE_3D 3 
miSURFACE_BUMP: 3 
miSURFACE_TEXBUMP_2D, non-rational: 5 
miSURFACE_TEXBUMP_2D, rational: 6 
miSURFACE_TEXBUMP_3D, non-rational: 5 
miSURFACE_TEXBUMP_3D, rational: 6 


degree[0] and degree[1] contains the degree of the surface in the U and V directions, respectively. 
This is used by GAP to cache the degree from the surface bases. 


no_parms[0] and no_parms[1] are the lengths of the U and V parameter vectors, respectively. 


no_ctls is the total number of control points for this surface. The number of scalars required in 
the scalar list is zo_ctls - ctl_dim. 


no_specpoints is the number of special points to be included in the tessellation. 


scalar_idx is the index of the first scalar in the surface scalar list (also anchored in the object, 
see above). The scalar list for one surface consists of the U parameter vector, followed by the V 
parameter vector, followed by the geometric control points (all X first, then all Y, then all Z, then 
all W, then all motion X, then all motion Y, then all motion Z, if present), followed by the texture 
and bump control points in the same XYZW order if present. 


specpnt_idx is the index of the first special point in the special points list (anchored in the object) 
to use. 


basis_idx[0] and basis_idx[1] are indices for the bases in the basis list (anchored in the object) to 
use, separate for the U and V parameter directions. 
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4.3.17 Surfaces: Curve Segment List 


Element type: miSCENE-CURVE 


Data type: miCurve 
Sizes: int no_curves 
Defaults: as described below 


enum miCurve_type { 
miCURVE_TRIM, 
miCURVE_HOLE, 
miCURVE_SPECIAL, 
miCURVE_SPACE 


}; 

typedef struct miCurve { 
miApprox approx; /* approx techn. for surface */ 
miBoolean new_loop; /* F=concat to prev, T=begin new */ 
miUshort ctl_dim; /* control point dimension 2 or 3 */ 
miUshort degree; /* from basis, for ease in GAP */ 
miGeoRange range; /* min/max for curve params. */ 
miGeoIndex no_parms ; /* number of curve parameters */ 
miGeoIndex no_ctls; /* number of control points */ 
miGeoIndex no_specpnts; /* number of special points */ 
miGeoIndex scalar_idx; /* index into curve_scalar list */ 
miGeoIndex specpnt_idx; /* index into special points list */ 
miGeoIndex basis_idx; /* index into basis list */ 
enum miCurve_type type; 
int pad; /* not used */ 


} miCurve; 


A translator must provide: type, approx, new_loop, ctl_dim, degree, range, no_parms, no_ct1s, 
scalar_idx, basis_idx. 
A translator may provide: no_specpnts, specpnt_idx. 


type specifies what the curve is used for. It must be one of miCURVE_TRIM, miCURVE_HOLE, 
miCURVE_SPECIAL or miCURVE_SPACE. The default is miCURVE_TRIM. 
approx is the approximation technique as described above, in the miFace description. 


new-loop is miTRUE for every new loop. Loops can be pieced together from multiple consecutive 
curves. The default is mi TRUE. 


ctl_dim is the control point dimension; 2 for UV curves or 3 for space curves. The default is 2. 
degree is the degree of the curve. The default is 3. 


range is the range over which the curve is evaluated. The value depends on the parameter list. 
The defaults are 0.0 and 1.0. 
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no_parms is the length of the parameter vectors. 


no-ctls is the number of control points for this curve. The number of scalars required in the curve 
scalar list is no_ctls - ctl_dim. 


no-_specpoints is the number of special points to be included in the approximation. 


scalar_idx is the index of the first scalar in the curve scalar list (also anchored in the object, see 
above). The scalar list for one curve consists of the parameter vector, followed by the control 
points (all X first, then all Y, then all Z, if present). 


specpnt_idx is the index of the first special point in the special points list (anchored in the object) 
to use. 


basis_idx is the index of the basis in the basis list (anchored in the object) to use. 


type describes what the curve is used for: trimming, hole, special, or space curve. 


4.3.18 Surfaces: Scalar Lists 


Element type: miSCENE-GEOSCALAR 
Data type: miGeoScalar[ | 

Sizes: int no_scalars 

Defaults: all nulls 


Both surfaces and curves store all their geometric data (parameter lists and control points) in 
unstructured scalar lists. The exact layout and the size of each control point depends on the 
surface or curve. Surfaces and curves store their scalars in separate scalar lists, but all surfaces in 
an object share one scalar list, and all curves in the object share the other (which is omitted if 
there are no curves). Each surface and curve has an index that specifies where in the respective 
scalar list the scalars for the surface or curve begin. All scalars for a single surface or curve are 
consecutive. The internal layout of each such curve depends on the surface or curve; see above 
for details. In general, the parameter vectors come first, followed by the control points in X, Y, 
Z, W order. All the X are given before the Y, etc. 


4.3.19 Surfaces: Curve Point Lists 


Element type; miSCENE-CURVPNT 


Data type: miCurve-_point[ | 
Sizes: int no_points 
Defaults: all nulls 


typedef struct miCurve_point { 
miGeoVector Vv; /* xyz on surface of curve at t */ 
miGeoVector2d uv; /* uv value of curve at t */ 
miGeoScalar t; /* curve parameter value */ 
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miUshort 

miUshort 

miCBoolean 

miCBoolean 

miCBoolean 

miCBoolean 
} miCurve_point; 


flags; 
spare_flags; 
Ae ig 

is_uv; 

LS. ¥% 

spare; 


/* 
/* 
/* 
f% 
/* 
/* 


internal use */ 

not used */ 

is t value present */ 
is uv value present */ 
is xyz value present */ 
not used */ 


A translator must provide: all fields except spare. 
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(Despite the name, curve points may also be referenced as special points by surfaces.) 


is_t, is_uv, and is_v, if miTRUE, specify that t, uv, or v are valid, respectively. 


t, if enabled by zs_t, gives the parameter value of the special point. 


uv, if enabled by is_uv, gives the UV value of the curve at the special point. 


v, if enabled by is_v, gives the location in space of the special point. 


4.3.20 Surfaces: Basis Lists 


Element type: miSCENE_BASIS_LIST 


Data type: miBasis_list[ | 
Sizes: int no_bases, int no-_scalars 
Defaults: all nulls 


enum miBasis_type { 


miBASIS_NONE = 0, 


miBASIS_BEZIER, 
miBASIS_BSPLINE, 


miBASIS_CARDINAL, 


miBASIS_MATRIX, 
miBASIS_TAYLOR 


ie 

typedef struct { 
miGeoIndex 
miGeoIndex 
miBasis 


} miBasis_list; 


typedef struct miBasis { 


no_bases; 
no_scalars; 


bases[1]; 


enum miBasis_type type; 


miGeoIndex 
miGeoIndex 
miGeoIndex 


degree; 
stepsize; 


value_idx; 


/* 


/* undefined for Cardinal */ 
/* only for miBASIS_MATRIX */ 


for internal use */ 


/* index into the basis scalar list */ 
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} miBasis; 


A translator must provide: type, degree; if the type is basis matrix, also stepsize and value_ 
idx. 


no_bases specifies the number of bases in the basis list. 

no-scalars specifies the number of scalars that follow the basis list. Scalars are used for basis 
matrix bases, which require degree scalars for a matrix defining the basis. The first scalar in the 
list has index 0. 


bases is the basis array. It is actually allocated larger. 


type is one of miBASIS_BEZIER, miBASIS_BSPLINE, miBASIS_CARDINAL, miBASIS_MATRIX, and 
miBASIS_TAYLOR. 


degree is the degree of the basis. 


stepsize is used for basis matrix bases only. For an explanation, see the description of bases in the 
mental ray User Manual. 


4.3.21 Space Curves 


Element type: miSCENE-SPACECURVE 


Data type: miSpacecurve[ | 
Sizes: int nO_spacecurves 
Defaults: all nulls except where otherwise noted 


typedef struct miSpacecurve { 


miApprox def_approx; /* default approximation */ 
miGeoIndex no_curves; /* total number of curves */ 
miGeoIndex curve_idx; /* index into the ’curves’ list*/ 
miBoolean pad; /* not used */ 

miVertex_content gap_vert_info; /* For calculating box sizes */ 


} miSpacecurve; 


A translator must provide: no_curves, curve_idx, gap_vert_info. 
A translator may provide: def_approx. 


def_approx is the default approximation for curve segments which do not have their own 
approximation defined. 


no_curves specifies the total number of curves used by this space curve. 


curve-_idx is the index of the first curve in the curve list anchored in the object that is used for 
this space curve. This is the first of mo_curves consecutive curves to use. 
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gap_vert_info describes the layout and size of the vertices to create during tessellation. The boxes 
created during tessellation will get a copy of this vertex info structure. 


4.3.22 Books and Pages 


Element type: miSCENE-BOOK 

Data type: miBook 

Sizes: miGeolIndex line_size, no_lines 
Defaults: all nulls except where otherwise noted 


#define miSCENE_BOOK_MAXSWAP 16 


typedef struct miBook { 


miUint label; /* type of book */ 
miGeoIndex no_pages ; /* number of used pages */ 
miGeoIndex first_page_size;/* number of lines on first page */ 
miGeoIndex line_size; /* size of elments in bytes */ 
miGeoIndex next_free_line; /* index of next free line */ 
miGeoIndex last_used_line; /* index of last used line */ 
char swap [miSCENE_BOOK_MAXSWAP] ; 
/* string for change of byte order */ 

miTag next_book; /* tag for next book */ 
miTag pages[1]; /* array of page tags */ 

} miBook; 


When a box is created the line size and the swap string must be supplied. The number of lines 
influences the size of the page. If it is smaller than some threshold a default page size is used. 


label is a variable at the disposal of the application using miBooks. It is not used by any of the 
book management functions described below. 


no_pages is the number of used memory pages. 


first_page_size is the number of lines on the first page. Consecutive pages grow in geometric 
progression. The details are implementation dependent and may change in the future. 


line_size is the size of the lines in bytes in the current book. 

next_free_line is the index of the element of the linked list of free lines. 

last_used_line’** helps mental ray to manage books more efficiently. 

swap is string of at most miSCENE_BOOK-MAXSWAP - 1 characters which indicates how the bytes 


in a line of a book should be swapped when being transferred between machines of different byte 
order. 
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next_book is a tag that allows to build chains of books. These may be accessed and enumerated 
more efficiently than single books. 


pages is an array of page tags. It is guaranteed to be big enough to hold all pages that might be 
allocated to keep the maximum total number of miMAX_GEOINDEX lines. 


None of the structure elements above except the label should be accessed directly. The same 
applies to the pages the books consist of. 


Element type: miSCENE-PAGE 

Data type: miPage 

Sizes: miGeoIndex page-size, line_size 
Defaults: all nulls except where otherwise noted 


typedef struct miPage { 


char swap [miSCENE_BOOK_MAXSWAP] ; 

/* string for change of byte order */ 
miGeoIndex page_size; /* number of lines on current page */ 
miGeoIndex line_size; /* size of elments in bytes * / 

} miPage; 


When a page is created the page and line sizes and the swap string must be supplied. However, 
pages should not be created directly but only through the calls to manage books described below. 


Swap is a string to indicate how lines should be swapped when pages are transferred between 
machines of different byte order. It has to stored in the pages too, because they are swapped 
independently of the books. 

page_size is the number of lines on the current page. 


line_size is the size of the lines on this page in bytes. 


Apart from the SCENE call interface function to create books etc., there are a number of extra 
functions to manage books: 


void *mi_scene_book_get_line( 
miBook *book, 
miGeoIndex line_num) 


Access a line with index line_num of a given book and returns a void pointer to it. 


void *mi_scene_book_allocate_line( 
miBook *book, 
miGeoIndex *line num) 
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Return a void pointer to a free element in a given book and set the line_num passed by reference. 
This may be a yet unused line or one that has been previously deleted with a call to mi_scene_ 
book_release_line. If the lines on existing pages are exceeded a new page is allocated. 


void mi_scene_book_release_line( 
miBook *book, 
miGeoIndex line_num) 


Delete a line from a given book. 


void mi_scene_book_enumerate ( 


miBook *book, 

void (*cb_func) (void *, 
miGeolIndex, 
void *), 

void *cb_data) 


Look at each element in a book in turn and if it is in use executes a call-back function. mi_scene_ 
book_enumerate takes three arguments. The first is a pointer to an miBook, the second a pointer 
to the call-back function, and the third a pointer to optional data that are passed to the call-back 
when it is called. If either the book or the call-back pointer is NULL nothing is done. Otherwise 
the book is traversed and for each valid element the function pointed to by the second argument 
is called. The argument of this call-back function are a pointer to the element in the book, its 
index and the optional data pointer. An element in a book is valid if it has been allocated by a call 
to mi_scene_book_allocate_line and not been freed subsequently by a call to mi_-scene_book_ 
release_line. Neither the call-back function nor mi_scene_book_enumerate return a value. 


miGeoIndex mi_scene_book_free_blk_start ( 
miBook *book) 


Return the index of the first line in the completely unused part of a book. 


miGeoIndex mi_scene_book_no_used_lines( 
miBook *book) 


Return the number of used lines in a book. 


miGeoIndex mi_scene_book_max_lines( 
miBook *book) 


Return the maximum allocated number of lines in a book. 
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miBoolean mi_scene_book_line valid( 


miBook *book, 
miGeoIndex line) 


Return miTRUE if a given line index refers to a used line and miFALSE otherwise. 


miTag mi_scene_book_attach( 


miTag old_book, 
miTag new_book, 
miGeoIndex position) 
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Concatenate chains of books. Insert the new book at the specified position in the chain and 
returns the tag of the first book in the chain after insertion. 


miTag mi_scene_book_detach ( 


miTag book, 
miGeoIndex position) 


Split off a component from a chain of books. Return the tag of the first book in the remaining 


chain. 


4.3.23 Materials 


Element type: 
Data type: 
Sizes: 
Defaults: 


typedef struct 


miSCENE_MATERIAL 
miMaterial 


all nulls 


miMaterial { 


miBoolean opaque ; 
miTag shader ; 
miTag displace; 
miTag shadow; 
miTag volume ; 
miTag environment ; 
miTag contour ; 
miTag photon; 
miTag photonvol ; 
mitag lightmap ; 
miTag hardware; 


} miMaterial; 


A translator must provide: shader. 
A translator may provide: all others. 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


no transparency? */ 
material shader */ 


opt. 
opt. 
opt. 
opt. 
opt. 
opt. 
opt. 


displacement shader */ 
shadow shader */ 

volume shader */ 
environment shader */ 
contour shader */ 
photon RT shader */ 
photon volume shader */ 


used for lightmaps */ 
hardware shader */ 
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opaque informs mental ray that the material is always opaque and casts an opaque shadow. This 
is a hint to mental ray and may not be used by all renderers. 


shader is the tag of a material shading function. It must refer to a database element of type 
miSCENE_FUNCTION. This tag may not be miNULLTAG. 


displace is the tag of an optional displacement shader function. 
shadow is the tag of an optional shadow shader function. 

volume is the tag of an optional volume shader function. 
environment is the tag of an optional environment shader function. 
contour is the tag of an optional contour shader function. 

photon is the tag of an optional photon shader function. 
photonvol is the tag of an optional photon volume shader function. 
lightmap°* is the tag of an optional lightmap shader function. 


a. 


hardware’ is the tag of an optional hardware shader. 


Note that mental ray 3.3 will append several new fields to this structure. Shaders keeping a local 
copy of a miMaterial will have to be recompiled for mental ray 3.3. 


4.3.24 Rendering Options 


Element type: miSCENE-OPTIONS 


Data type: miOptions 
Sizes: — 
Defaults: as described below 


The rendering options were designed to accommodate as wide a range of renderers as possible, 
from simple wireframe displayers to complex ray tracers. The interpretation of the structure 
members is left to the renderer. Generally, no renderer will require all provided fields; each 
renderer may use a different subset. 


typedef struct midptions { 


miBoolean trace; /* 2nd generation ray trace? */ 
int scanline; /* O=off, 1=on, ’o’=OpenGL */ 
miBoolean motion; /* motion blur? : miFALSE */ 
miBoolean shadow_sort; /* Obsolete! Do not use */ 
miBoolean preview_mode; /* for future use */ 

int reflection_depth; /* refl. trace depth : 1 */ 


int refraction_depth; /* refr. trace depth : 1 */ 


int 

int 

int 
miColor 
miColor 
miTag 
mitag 
miBoolean 
miBoolean 
int 

float 

int 

float 
float 
float 
float 
float 
float 
short 
short 
short 
miSinti 
miSinti 
int 

int 

float 

int 

miUint 
miTag 
miTag 
miCBoolean 
miUchar 
char 

char 
miCBoolean 
miCBoolean 
char 

char 

char 
miCBoolean 
char 

char 

char 

char 

char 

char 
miCBoolean 
miCBoolean 
miCBoolean 
miCBoolean 
int 
miBoolean 
miTag 
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trace_depth; 
min_samples; 
max_samples; 
contrast ; 
time_contrast; 
contour_contrast; 
contour_store; 
caustic; 
globillum; 
caustic_accuracy; 
caustic_radius; 
globillum_accuracy; 
globillum_radius; 
caustic_filter_const; 
filter_size_x; 
filter_size_y; 
jitter; 

shutter ; 
grid_res[3]; 
grid_max_size; 
grid_max_depth; 
def_min_samples; 
def_max_samples; 
space_max_size; 
space_max_depth; 
shutter_delay; 
no_images ; 

spare1 [47] ; 
images_info; 
finalgather_file; 


space_shadow_separate; 


finalgather_filter; 
rapid_collect_rate; 


rapid_motion_resample; 


use_shadow_maps ; 


rendering shadow_maps; 
recompute_shadow_maps ; 


shadow; 
caustic_filter; 
finalgather_rebuild; 
fister; 
acceleration; 
face; 

field; 

smethod; 
render_space; 
pixel_preview; 
task_preview; 
visible_lights; 
shadow_map_motion; 
task_size; 

strips; 
photonmap_file; 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
f* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
T* 
/* 
/* 
f* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 


refl. + refr. depth : 1 */ 
min. sampling level : -2 */ 
max. sampling level : 0 */ 
sampling contrast: .1 */ 
temporal sampling contrast*/ 
NULLTAG */ 

NULLTAG */ 

enable caustics: miFALSE */ 
enable global il.: miFALSE*/ 
no. caus. photons in est. */ 
maxdist for caus. photons */ 
no. glob. photons in est. */ 
maxdist for glob. photons */ 
filter const. for caus. */ 


filter size in = : 1,0:4/ 
filter size in y : 1.0 */ 
sample jittering : 0.0 */ 


shutter speed for motion:0*/ 
grid resolution */ 

max obj. in grid cell */ 

max grid nesting */ 

min/max samples for objs */ 
without min/max, -128 127 */ 
Space subdiv. leaf size: 4*/ 
space subdiv. depth : 25*/ 
shutter open time: 0 */ 

# images : 1 */ 

keep ray33 offsets */ 

frame buffers */ 

finalgather map file: 0 */ 


space subdiv shadow struct */ 


finalgather ray filter */ 
rasterizer only */ 
rasterizer only */ 

use shadow maps ? 0 */ 
Shadow map mode? 0 */ 
’n’o,’y’es (could be Bool) */ 
shadow casting? */ 
filter-type */ 

rebuild FG ?: on*/ 

sample filter type */ 
acceleration: ’b’ */ 
primitive facing */ 

field rendering? */ 

sampling algorithm */ 
coordinate space */ 

pixel selective sampling */ 
task selective sampling */ 
any visible area lights? */ 
motion blurred shadowmaps?*/ 
image task size */ 

create triangles in strips*/ 
photon map file name */ 
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miBoolean 
int 

int 

int 

int 
miColor 
miColor 
miColor 
miUint 


float 
miTag 
miTag 
miTag 
miCBoolean 
miCBoolean 
miCBoolean 
miCBoolean 
miUinti 
miCBoolean 
miUinti 
char 

int 

float 
miUinti 
miCBoolean 
miCBoolean 
miCBoolean 
miCBoolean 
miUinti 
miCBoolean 
miCBoolean 
miCBoolean 
miUinti 
miUinti 
miUinti 
miUinti 
float 
float 
miTag 
miApprox 
miApprox 
miBoolean 
int 

float 
float 
float 
float 
miBoolean 
miBoolean 
miBoolean 
int 

float 


photonmap_rebuild; 


/* 


photon_reflection_depth;/* 
photon_refraction_depth;/* 


photon_trace_depth; 
space_max_mem; 
caustic_scale; 
globillum_scale; 
finalgather_scale; 
spare2[15]; 


lum_efficacy; 
white_cprof; 
render_cprof ; 
fb_dir; 

no_lens; 
no_volume; 
no_geometry ; 
no_displace; 
no_output ; 
no_merge; 
caustic_flag; 
diagnostic_mode; 
photonvol_accuracy ; 
photonvol_radius; 
globillum_flag; 
samplelock; 
autovolume; 
finalgather_view; 
no_hair; 
n_motion_vectors; 
no_pass; 
photon_autovolume ; 
no_predisplace; 
fg_reflection_depth; 
fg_refraction_depth; 
fg_diffuse_depth; 
fg_trace_depth; 
fg_falloff_start; 
fg_falloff_stop; 
userdata; 

approx; 
approx_displace; 
finalgather ; 
finalgather_rays; 


finalgather_maxradius 
finalgather_minradius ; 


diag_photon_density; 
diag_grid_size; 
desaturate; 

dither; 

nopremult ; 
colorclip; 

gamma ; 


/* 
/* 
/* 
/* 
/* 
/* 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
f* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
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photon map rebuild ? */ 
photon refl. depth */ 
photon refl. depth */ 

total photon trace depth */ 
maximum bsp memory (mb):0 */ 
caustic multiplier */ 
globillum multiplier */ 
finalgather multiplier */ 
keep ray33 offsets */ 


render space luminous efficacy*/ 
white adapt. col. space */ 
color profile render space*/ 
frame buffer directory */ 
disable lens shaders */ 
disable volume shaders */ 
disable geometry shaders */ 
disable displace shaders */ 
disable output shaders */ 
disable surface merging */ 
def. caustic flag for objs*/ 
miSCENE_DIAG_* flags */ 

no. vol. photons in est. */ 
maxdist for vol. photons */ 
def. globil. flag for objs*/ 
steady samples?: on */ 
internal volumes? */ 

radii in raster pixels ? */ 
disable hair rendering */ 
global number of motions */ 
disable multipass render * 
autovolume for photons */ 
disable displ presampling */ 
finalgather refl. depth */ 
finalgather refr. depth */ 
#secondary fg bounces */ 
total fg trace depth */ 
finalgather falloff start */ 
finalgather falloff stop */ 
optional user data blocks */ 
approximation overrides if*/ 
style != APPROX_STYLE_NONE*/ 
fg. for globillum: miFALSE*/ 
no. rays in final gather */ 
maxdist for finalgather */ 
mindist for finalgather */ 


density for diag */ 
gridsize for diag */ 
for IMG: fade to white? */ 
for IMG: LSB dithering? */ 


for IMG: A < RGB ok? */ 
for IMG: miIMG_COLORCLIP* */ 
for IMG: gamma, default 1 */ 
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miTag inh_funcdecl; /* inheritance function */ 

miColor luminance_weight ; /* weights to calc intensity */ 

int split_obj_no_triangs; /* max no_triangs for split */ 

int split_obj_no_faces; /* max no_faces for split */ 

miCBoolean inh_is_traversal; /* inh_funcdecl is traversal */ 

miUint1 hardware ; /* hw rendering: on|off|al1*/ 

miUinti hardware_diagnostic; /* flags for diagn. mode */ 

miUint1 shadowmap_flags; /* flag for shadowmaps */ 

float maxdisplace; /* override if !=0: default 0*/ 

miScalar shadowmap_bias; /* move shmap Z back by bias */ 

miUint1 hwshader ; /* O=cg 1=oglsl/hlsl 2=fast */ 

miCBoolean photonmap_only; /* render photon map only */ 

miUint1 lightmap; /* O=off,1=on,2=only */ 

miTag state_func; /* allow user to init state */ 

float fg_presamp_density; /* samples density for precomp. 

* finalgather points */ 

float rapid_shading_samples; /* shading samples per pixel */ 
/* default: 1.0f */ 

miCBoolean fb_virtual ; /* mmap frame buffers */ 

miCBoolean spare3([3] ; /* not used */ 

int spare[10]; /* not used */ 
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} miOptions; 


A translator must provide: nothing. 
A translator may provide: all fields. 


trace (default miTRUE) enables ray tracing. The trace flag is obsolete as of mental ray 3.4. Code 
that writes to the trace field should write to the reflection, refraction, and finalgather flag bitmaps 
instead. 

scanline (default miTRUE) enables the first-generation scanline algorithm if applicable to improve 
speed. miFALSE disables scanline rendering, and ’o’ replaces the standard scanline renderer with 
an OpenGL renderer that used the OpenGL hardware of the system for fast rendering (SGI 
only). 

motion (default miFALSE) enables motion blurring. 

preview_mode (default miFALSE) not currently used. 

reflection_depth (default 1) limits the ray tracing depth for reflection rays. 

refraction_depth (default 1) limits the ray tracing depth for refraction or transparency rays. 


trace_depth (default 1) limits the ray tracing depth for the sum of all rays. 


min_samples (default -2) specifies the minimum number of samples in each direction in recursive 
oversampling mode. At least 2””~#?/s samples in each direction will be taken. 
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max_samples (default 0) specifies the maximum number of samples in each direction in recursive 
oversampling mode. At most 2”4*=#”?s samples in each direction will be taken. 


contrast (default 0.1 0.1 0.1 0.1) specifies the contrast limit above which more spatial samples are 
taken. 


time_contrast (default 0.2 0.2 0.2 0.2) controls the number of temporal samples used for motion 
blur rendering. The value is approximately exual to the inverse of the number of the temporal 


samples. Because of blurring, this can usually be much higher than the spatial contrast. 


contour_contrast (default no shader) specifies a function that computes contrasts in contour 
rendering mode. 


contour-store (default no shader) specifies a function that collects and stores sample information 
for use by the contour contrast function, in contour rendering mode. 


caustic specifies whether caustics should be rendered. 


globillum specifies whether global illumination should be rendered. This mode is available only 
in version 2.1 or later. 


caustic_accuracy specifies the number of photons to use when estimating radiance for caustics. 
caustic_radius specifies the maximum distance in which photons used in the radiance estimate 
for caustics are located. If the radius is 0.0, then an estimate based on the scene extent will be 


used. 


globillum_accuracy specifies the number of photons to use when estimating radiance for global 
illumination. 


globillum_radius specifies the maximum distance in which photons used in the radiance estimate 
for global illumination are located. If the radius is 0.0, then an estimate based on the scene extent 
will be used. 

caustic_filter_const is a constant used when filtering caustics radiance estimates. 

filter_size_x (default 1.0) specifies the width of the filter specified in the filter field. 
filter_size_y (default 1.0) specifies the height of the filter specified in the filter field. 


jitter (default 0.0) is the jitter interval. Jittering displaces samples to avoid sampling artifacts. 


shutter (default 1.0) is the shutter time of the camera if motion blurring is enabled. It may not 
be negative. 


subdivision, subdivision_2d, and subdivision_memory are obsolete. 
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grid_res"' (default 00 0) controls the voxel grid resolution in X, Y, and Z directions, if acceleration 
is set to ’g’ (grid). If all three are 0, mental ray uses a default computed from the scene. 


grid_max-size’:' (default 128) controls the maximum size of each grid voxel, if acceleration is set 
to ’g’ (grid). 


grid_max_depth°"! (default 2) controls the maximum nesting depth of grids, if acceleration is set 
to ’g’ (grid). 


min_def_samples>:' (default -128) applies to all samples (eye rays including all their secondaries) 
that have not hit any objects with a min_samples field. It specifies the minimum oversampling 
for such samples. Effectively, it acts as the default in per-object oversampling mode. Like object 
min/max parameters, it must stay in the overall sampling range specified by min_samples ... max- 
samples. -128 turns it off; min_samples will be used. 


max_def_samples*:' (default 127) applies to all samples (eye rays including all their secondaries) 
that have not hit any objects with a max_samples field. It specifies the maximum oversampling 
for such samples. Effectively, it acts as the default in per-object oversampling mode. Like object 
min/max parameters, it must stay in the overall sampling range specified by min_samples ... max- 
samples. 127 turns it off; max_samples will be used. 


space_max_size (default 4) is the maximum leaf size in BSP mode. 
space_max_depth (default 24) is the maximum tree depth in BSP mode. 


shutter_delay*! (default 0) allows starting the shutter open interval late. It ranges from 
t = shutter_delay to shutter. This is useful for shifting the evaluation time to the center of 
the frame by setting shutter_delay and shutter to the same value, such as 0.5, and then doing 
bidirectional postprocessing motion blur. 


no_images (default 1) is the number of valid entries in the zmages_info array described below. 


images_info°* is a database array which specifies the frame buffers. There are o_images entries 
in the array. Each entry has the type miFb_info, which is described below. Frame buffers may be 
accessed only in output shaders. Note that output shaders need to be changed for mental ray 3.4 
to implement the new frame buffer access methods. 


typedef struct miFb_info { /* mental ray 3.4 and later! */ 
milmg_type image_type; /* image types */ 
miUint4 write_image; /* bits: O=sample image */ 
/* 1=write image */ 
miBoolean interp_image /* interpolate image? */ 
} miFb_info; 


See the documentation of the IMG module for a list of allowed types. image_types (default 
miIMG_TYPE_RGBA) specifies the image types to be generated during rendering. 
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write_image (default 3) specifies for each image whether it is sampled (if bit 0 is 1) and written 
to a file (if bit 1 is 1) after rendering completes. mental ray 2.1 combined both bits into a single 
boolean. 


interp_image (default miTRUE, miFALSE, ...) specifies for each image whether it is to be 
interpolated. This means that if fewer than one sample per pixel is taken, the holes are filled in. 


finalgather_file’* is a string containing the filename of a file from which a finalgather point 
map should be loaded (if possible) or otherwise saved to. If this tag is a miNULLTAG then no 
finalgather map is loaded or saved. 


space_shadow-separate’' turns on separate BSP trees for traceable and shadow geometry. The 
trace and shadow flags are attributes of geometric objects. Objects that have both flags go into 
both BSP trees, which its less efficient. 


finalgather_filter’? specifies the size of the final gathering speckle removal filter. 0 means off; 
values greater than 4 are not normally useful. 


rapid_collect_rate’” specifies the number of samples rendered, per pixel dimension. If set to 0, it 
defaults to 4, which gives 16 samples per pixel. 


shading-_samples’? specifies the number of shading calls per pixel. If set to 0, it defaults to 1. 


rapid_motion_resample’? controls the number of points in time sampled by the rasterizer 
(formerly called Rapid Motion). 


use_shadow_maps, if miTRUE, specifies that shadowmaps should be used for the light sources 
which have shadowmaps. If set to ’0’, shadowmaps are computed using OpenGL. mental ray 
3.2 allows independently setting bit 7 to render only shadowmaps to files, if applicable, but omit 
the main rendering stage (-shadowmap only). This flag applies to all shadowmaps in the scene. 


The default is off (0). 


rendering _shadow_maps is miTRUE when the shadowmaps are being rendered. This option is 
internal to RC and only used to optimize the rendering of shadowmaps. 
recompute_shadow_maps can be ’y’ or ’n’.’’y’ means that all shadowmaps are recomputed even 
if they could have been loaded from a file. ’n’ means that shadowmaps are only computed if they 
could not be re-used or loaded from a file (shadowmaps are recomputed "intelligently" meaning 
that the shadowmap code tries to identify those light sources for which a new shadowmap needs to 
be recomputed. This recomputation currently only applies to light sources for which the position 
or direction of the emitted light — ie. the transformation matrix — changes in an animation). 


shadow (default 1) controls shadow casting. It is one of 0 (no shadows), 1 (normal shadows), ’s’ 
(shadow segments with separate volume shaders), and ’1’ (shadow intersections sorted from the 


light source towards the illumination point). 


caustic_filter is the type of filter used: ’b’ box filter, ’c’ cone filter and ’g’ gauss filter. 
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filter (default ’b’) is one of ’b’ (box filter), ’t’ (triangle filter), ’g’ (Gaussian filter), ’m’ 
(Mitchell filter), or 71’ (Lanczos filter). 


acceleration (default ’b’) is one of ’b’ (space subdivision, BSP), ’1’ (large-scene BSP), and 
’g’ (grid). 

face (default ’a’) enables backface culling, one of ’f’ (front-facing only), ’b’ (back-facing only), 
and ?a’ (both). During rendering, mental ray 3.x copies the face flag to the shader state to make 
it controllable by shaders. 

field is not used. 


smethod is not used. 


render_space is ’o’ for object space (recommended) or ’c’ for camera space (default for backwards 
compatibility). 


pixel_preview is set when pixel previewing should be used. The default is off. 
task_preview is set when task previewing should be used. The default is off. 


visible_lights is set if there are any area lights with the ’visible’ flag. This option is internal to RC 
and used to optimize rendering. 


shadow_map-_motion enables motion blurring of shadowmap shadows. The default is on. 
task_size (default 0) is the size of the image tasks to be rendered. If it is zero, a heuristic based on 
the image resolution will be used in RC in order to calculate an appropriate value. task_size can 


also be specified explicitly. 


strips specifies whether the approximated geometry is represented as triangle strips and fans. The 


default is off. 
photonmap file is a string containing the filename of a file from which a photon map should be 
loaded (if possible) or otherwise saved to. If this tag is a miNULLTAG then no photon map is 


loaded or saved. 


photonmap_rebuild will, if true, enforce a recomputation of the photon map even if it could 
have been loaded from a file. 


photon_reflection_depth controls the trace depth of reflected photons. The default is 5. 
photon_refraction_depth controls the trace depth of refracted photons. The default is 5. 


photon_trace_depth controls the combined trace depth of reflected and refracted photons. The 
default is 5. 


caustic_scale’* is multiplied into the indirect illumination from caustics. Factors greater than 1 


562 4 Geometry Shaders 


increase the brightness of the effect. If just this option is changed, it is correct to re-render scene 
with photonmap_rebuild set to false. 


globillum_scale’* is multiplied into the irradiance obtained from global illumination photonmap 
lookup. Factors greater than 1 increase the brightness of the effect. If just this option is changed, 
lookup g | g p g 

it 1s correct to re-render scene with photonmap_rebuild set to false. 


finalgather_scale’* is multiplied into the indirect illumination obtained from final gathering. 
This allows fast artistic tuning of indirect illumination. If just this option is changed, it is correct 
to re-render scene with finalgather_rebuild set to false, saving the finalgather preprocessing 
step. 


lum_efficacy’* (default 1) is a constant with units lumen per Watt. If the calculations in the 
rendering color space are performed in radiometric units, then the result may be multiplied by 
this constant to obtain photometric units. For physically correct rendering this value should be 
683 lumen per Watt. Selecting a value unequal to one may require selecting an output file format 
capable of storing arbitrary floating point numbers. mental ray does not distinguish between 
radiometric and photometric units by default. The luminous efficacy should only be set to a 
non-unit value if there are specific reasons requiring this step. 

white_cprof’*is a tag associated with a color profile used to perform all white point point 
adaptions when transforming from the rendering color space to the output color profile. If this 
value is not set, then any white point adaptions are performed in mental rays internal color space. 


render_cprof?*is a tag associated with a color profile describing the rendering color space. If this 
value is not set, then rendering is performed in a device dependent color space which is identical 
with the output color space. If the value is set to a valid color profile, then rendering is performed 
in this color space. The results in the color frame buffer are stored in mental rays internal color 


space. 


fb_dir** is a string containing the directory for frame buffer files on disk. If this is a null tag then 
defaults are taken from environment variables. 


no_lens, if miTRUE, disables all lens shaders. The default is miFALSE. 

no_volume, if miTRUE, disables all volume shaders. The default is miFALSE. 
no_geometry, if miTRUE, disables all geometry shaders. The default is miFALSE. 
no_displace, if mi TRUE, disables all displacement shaders. The default is miFALSE. 


no_output is a bitmap. Bit zero, it set, disables all output shaders. Bit one, if set, disables writing 
of output image files. The default is zero for both bits. 


no_merge, if miTRUE, disables all edge merging and adjacency detection. The default is miFALSE. 


caustic_flag is the default caustic flag for objects. The default value is 3, making all objects caustic 
generators and caustic receivers. 
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diagnostic_mode controls alternate rendering modes for diagnostic purposes. It is a bitmap. The 
only currently supported bit is miSCENE_DIAG_SAMPLES which, when set, turns on sample view 
mode. The default value is zero for all bits. 


photonvol_accuracy specifies the number of photons to use when estimating radiance inside 
participating media. 


photonvol_radius specifies the maximum distance in which photons used in the radiance estimate 
for participating media are located. If the radius is 0.0, then an estimate based on the scene extent 
will be used. 


cut_windows7'! enables rendering every image as 7 x n cut windows if set greater than zero. 


cut_expand?" increases the cut window frustum by a factor all around the frustum if greater 
than zero, to catch invisible outside geometry that becomes visible because it is displaced into the 
frustum. The default is 0.1. It has an effect only if cut windows are enabled. 


globillum_tflag is the default globillum flag for objects. The default value is 3, making all objects 


globillum generators and receivers. 


samplelock (default mi TRUE) uses the same sampling sequences for every frame, causing sampling 
noise to remain unchanged in unchanged parts of the scene. If set to miFALSE, the sequences are 
initialized with the frame number to cause moving noise. 


autovolume (default miFALSE enables automatic volume tracking by mental ray. This allows 
managing overlapping volumes and a camera that is inside one or more volumes, to always call 
the correct volume shaders. 


finalgather_view (default miFALSE) switches the final gather radius parameters from world space 
to projected raster space. 


no_hair>"', if set, disables hair rendering. 


n_motion_vectors:! specifies the number of curve segments into which motion transformations 
should be subdivided to create a smooth curved motion path. This must be a number in the range 
1..15. The default is 1. The scene language equivalent is motion steps. 


no_pass>'' disables multipass rendering. All pass statements in the camera will be ignored. 


photon_autovolume’” enables autovolume mode for photons. Autovolume mode keeps track 
of the volumes or list of volumes that a photon is in, depending on volume shaders and their 
mixing properties on materials. 

no_predisplace’* turns off displacement presampling, which normally attempts to improve 
bounding box quality by checking a number of displaced points for extreme values. 


fg reflection_depth*? is a trace depth for reflected finalgather rays. This implements multi- 
generation final gathering in a way similar to reflection_depth for regular rays. mental ray versions 
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prior to 3.4 did not trace multigeneration finalgather rays. For mental ray versions prior to 3.4 
this options only restricts depth of specular and glossy reflected child rays of finalgather rays. 


fg_refraction_depth’? is a trace depth for refracted finalgather rays. 

fg_diffuse_depth** is a trace depth for secondary diffuse bounces. 

fg trace_depth>” is a total trace depth for reflected and refracted finalgather rays. 

fg _falloff_start’ specifies the starting distance for finalgather falloff. 

fg _falloff_stop’ specifies the stopping distance for finalgather rays. The total length of finalgather 
rays cannot exceed the stop distance, and is attenuated with a linear falloff curve between the 
start and stop distances. If both are set to 0.0, no falloff takes place. 

approx overrides all base surface approximations in objects, both free-form surfaces and 
polygonal, if the approximation style is not miAPPROX_STYLE_NONE. This style is the default, 
and all other fields are 0. Use the miAPPROX_DEFAULT macro to activate this approximation. See 
the miApprox data structure description above. 

approx_displace is the same thing for displacement approximations. 

finalgather enables final gathering. The default is off. 

finalgather_rays is the number of rays shot in each final gather. The default is 1000. 


finalgather_maxradius is the maximum radius in which a final gather result can be used for 
interpolation or extrapolation. If this radius is 0.0, then an estimate based on the scene extent will 


be used. 


finalgather_minradius indicates that a final gather result must be used for interpolation or 
extrapolation if it is within this distance. If this radius is 0.0, it will be set to 10% of finalgather_ 
maxradius. 


diag_photon_density°* scales the diagnostic photon density mode by defining the density where 
the diagnostic color range peaks. 


diag _grid_size** defines the grid width of the diagnostic grid mode. 
desaturate’* used to be set with mi_img_mode?". If enabled, colors exceeding the 0..1 range will 
not be clipped per component, but the whole color is faded to white. This has an effect only when 


storing colors in 8-bit or 16-bit color frame buffers. 


dither’* was also handled by mi_img_mode*:!. It enables LSB dithering when storing colors in 
8-bit or 16-bit color frame buffers, to avoid color banding. 


nopremult>* was also handled by miimg_mode?". It turns off premultiplication when storing 
colors in the frame buffer. 
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colorclip>* was also handled by mi_img_mode?". Sets the color clipping when storing colors in 
8-bit or 16-bit color frame buffers to miIMG_COLORCLIP_RGB (preserve RGB and adjust alpha), 
miIMG_COLORCLIP_ALPHA (preserve alpha and adjust RGB), or mi IMG_COLORCLIP_RAW (disable 
color clipping). 

gamma?>* was also handled by mi_img_mode?!. It applies gamma correction if gamma is less 
than or greater than 1.0, when storing colors in 8-bit or 16-bit color frame buffers. 


}3-* 


inh_funcdecl’* contains the inheritance function. 


luminance_weight** (default =, $, +) controls the weights that miluminance will assign to R, G, 


and B, respectively, to compute the luminance value. 
split_obj_no_triangs°* is not used. 
split_obj_no_faces’* is not used. 


inh_is_traversal’:! (mental ray 3.1.2), if true, switches the inheritance function described by inh_ 
funcdecl to a traversal shader. It works the same way but gets a different argument set that is more 
powertul. New projects should rely on traversal functions instead of inheritance functions. 
hardware’® is used for internal purposes only. It controls when mental ray will use hardware 
shaders: never, if available, or always (even if the shading result can only be approximated). 


hardware_diagnostic®” is reserved for future use. 


shadowmap_flags> is a bitmap of bits 0 (shadowmap merge), and bit 3 (shadowmap only). The 
other bits must be cleared. 


maxdisplace’’, if set to a value other than zero, overrides the maxdisplace values when 
approximating a displaced object. This is useful if an old scene without object maxdisplace 
values must be rendered without truncating all displacement to zero. 


shadowmap_bias supplies a shadowmap bias value to all shadowmaps attached to light sources. 
This is a simple way to switch all of mental ray to biased shadowmaps without modifying all 
lights. 


hwshader is a bitmap of hardware allowed shading modes that mental ray will try in turn until 
one succeeds: 


e miHW_DEFAULT: use the best shading mode. 


e miHW_FORCE: force hardware rendering even if the following modes fail. Never fall back on 
software. This may result in gray default surfaces. 


e miHW_CG: try programmable Cg shaders. 


e miHW_NATIVE: try OpenGL Shading Language. (This is currently not well-supported, added 
in future releases when the OpenGL standard is finalized.) 
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e miHW_FAST: try non-programmable OpenGL, which can handle only very simple vertex 
shading models. 


photonmap_only°’* if true, means that only the photon maps and not the camera images are 


rendered. The default is false. 


lightmap”* flag controls rendering of lightmaps. The settings are 0 (off), 1 (on), and 2 (only). By 
default, lightmaps are enabled. If this option is set to 2, only the lightmaps and not the camera 
images are rendered. 


state_func>”? is the tag of the optional state shader that is called at the beginning and end of the 
lifetime of a state or a primary ray or similar shader call. 


fe _presamp_density’* controls the density of initial finalgather points. It increases (decreases 
if fg_presamp_density < 1) the number of finalgather points computed in the initial stage 
approximately fg_presamp_density times. 


rapid_shading samples** sets the number of shading samples per pixel for the rasterizer (default 
is 1.0). Only has an effect in conjunction with scanline = ’rapid’. 

fb_virtual’* controls whether frame buffers are maintained in memory (false) or memory- 
mapped to disk (true). The default is true, which allows an arbitrary number of frame buffers or 
arbitrary size without filling up memory, but for some applications such as fast preview rendering 
it may be faster to set this flag to false. 


4.3.25 Images 


Element type: miSCENE_IMAGE 


Data type: milmg_image 
Sizes: — 
Defaults: all nulls 


typedef struct milmg_image { 


miBoolean filter; /* caller wants filtered lookups */ 
toh dirsize; /* valid # of filter levels */ 

int dir [miIMG_DIRSIZE]; /* offs from this to other imgs */ 
int width, height; /* width and height in pixels */ 

int BLES; /* requested bits per comp, 8/16/32 */ 
int comp; /* requested components/pixel, 1..4 */ 
miCBoolean local; /* local texture, use image/mmap/path*/ 
miCBoolean writable; /* writable texture (eg. light map) */ 
miCBoolean cacheable; /* cache in parts */ 

miCBoolean remap ; /* image is remapped */ 

int type; /* requested miIMG_TYPE_* */ 

miTag real_name; /* (local) file name to open */ 

miTag colorprofile; /* color profile for image data */ 


int c[4]; /* indexed by miIMG_*; 4*height */ 
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/* component indices follow, */ 
/* then component scanlines */ 
} miImg_image; 


A translator must provide: nothing. 
A translator may provide: nothing. 
Provided by mi_scene_create: all fields. 


Images consist of three sections: the header (type milmg_image), a list of scanlines indices, and 
the actual uncompressed pixel data. There are height - 4 scanline indices, one set of comp (up to 4) 
indices for each scanline. They contain indices relative to the first pixel data byte. The pixel data 
is arranged in one-component scanlines of width component values each. All images are scanned 
bottom-up. 


filter, if nonzero, enables pyramid texture mode. 
dirsize and dir are used for internal purposes. 
width is the number of pixels per scanline. 
height is the number of scanlines. 

bits is the number of bits per component pixel. 
comp is the number of components per pixel. 


writable*>*, if true, specifies a writable texture. Such textures are created by shaders, usually 
lightmap shader’, and then written to disk. 


cacheable®"', if true, is used internally to mark images that are paged into a texture cache. Do not 
set. 


remap”, if true, specifies that the image is a .map file created with imf_copy -r, which rearranges 
pixels so that the unit of caching is a ractangle instead of a group of scanlines. This increases cache 
performance for large textures. 


local, if true, specifies a local image that each slave on the network must read locally, instead of 
fetching it across the network from the master. 


type is the data type of the image. 


real_name”'' is the tag of a database item of type string (contains a null-terminated ASCII string) 
that is the full path of the file to open. This name is used for local images, where the file is opened 
when first accessed (after the usual filename rewriting). For this purpose, the path is not sufficient 
because it may be truncated. mental ray 3.0 accesses a symbol table to find the name specified with 
mi_api_texture_file_def instead of relying on real_name, because the file may be demand-loaded 
or memory-mapped, so that real_name may be unavailable or incorrect. 
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color_profile’* is a tag associated with the color profile describing the color space of the image 
color data. When the image data are created and rendering was performed in a prescribed color 
space, then the color data are transformed to the specified color profile before they are written. 
If the image data are read, then they are transformed from the given representation to the color 
profile associated with the rendering color space. 


c is the first scanline index block. Only comp of the 4 available indices are used. It is unused if 
local is true. 


4.3.26 Strings 


Element type: miSCENE-STRING 
Data type: char[ | 

Sizes: int no_chars 
Defaults: _ 


Strings hold standard null-terminated character strings. They are used for the string shader 
parameter type and for shadowmap file names in lights, and for other purposes. The number of 
characters passed when creating or resizing the string must include the trailing null byte. 


4.3.27 Tag Lists 


Element type: miSCENE-TAG 
Data type: milag[ | 

Sizes: — 

Defaults: 


Tag lists are used for various purposes, such as material lists stored in the material field of instances. 


4.3.28 Color Profiles>* 


Element type: miSCENE-COLORPROFILE 
Data type: miColor_profile[ ] 

Sizes: — 

Defaults: all nulls 


typedef struct miColor_profile { 


miUint1 space; /* color space */ 

miCBoolean white_adapt ; /* perform white space adaption */ 
miScalar gamma ; /* gamma correction (XYZ->space) */ 
miColor white; /* CIE XYZ white point */ 

miScalar trafo[9]; /* CIE XYZ to color space trafo */ 
miScalar inv_trafo[9]; /* color space to CIE XYZ trafo */ 


} miColor_profile; 
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A translator must provide: space 
A translator may provide: all fields 
Provided by mi_scene_create: 


Color profiles allow distinguishing between the color space used for rendering and the color space 
used for output. If no color spaces are provided, then mental ray will perform all rendering and 
output in a device dependent color space. The ability to select a rendering color space different 
from the output color space allows mental ray to adapt to more stringent user requirements. 


space identifies the color space to be associated with this color profile. There is a list of predefined 
color spaces, but it is also possible to specify a custom color space, provided the transform to this 
space from the CIE XYZ color space may be described by a three by three matrix. 


white_adapt flags if transformations from or to this color space should include a white point 
adaption. 


gamma gives the gamma correction exponent needed to transform a CIE XYZ color triple to the 
color space described in the color profile. mental rays color profiles consider gamma corrections 
independent of the color space, even though the standards for sRGB or HDTV include gamma 
correction values. However, gamma correction is aimed at the viewing device, while mental 
rays results should be considered device independent. However, sometimes it is of advantage 
to perform the gamma correction before the result is written out. Therefore optional gamma 
correction has been included with color profiles. 


white contains the CIE XYZ values of the white point for this color profile. 


trafo[9] If the color space is selected as custom, then the three by three transformation matrix for 
mapping color values in CIE XYZ space to the custom color space may be stored in this array. 


inv_trafo[9] If the color space is selected as custom, then the three by three transformation matrix 
for mapping color values from the custom color space to CIE XYZ may be stored in this array. 


4.3.29 Light Profiles** 


Element type: miSCENE-LIGHTPROFILE 
Data type: miLight_profile[ ] 

Sizes: — 

Defaults: all nulls 


typedef enum miLight_profile_basis { 
miLP_BASIS_NONE = Q, 
miLP_BASIS_HERMITE = 1 

} miLight_profile_basis; 


typedef enum miLight_profile_std { 
miLP_STD_NONE = 0, 
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miLP_STD_IES 
miLP_STD_EULUMDAT 
} miLight_profile_std; 


ll 
NO 


typedef struct miLight_profile { 
miLight_profile_std format; /* data file standard */ 


miLight_profile_basis base; /* basis for interpolation */ 
int quality; /* interpolation quality */ 
miTag filename; /* orig data file */ 

int n_vert_angles; /* there are n theta angles */ 
int n_horz_angles; /* there are n phi angles */ 
int flags; /* symmetry properties */ 


} miLight_profile; 


A translator must provide: all fields. 
A translator may provide: all fields. 
Provided by mi_scene_create: 


The intensity of light emitted by a light source may depend on the emission direction. Light 
profiles allow describing such dependencies. There are two data formats, IES and Eulumdat, 
widely used by manufacturers of illumination devices to describe the intensity distributions of 
their light sources. mental ray can read these data formats and transform them to an internal 
representation, described by a light profile. 


format describes the file format of the light profile data. Allowed values are miLP_STD_IES and 
mLPSTD_EULUMDAT 


base describes the interpolation method used on the internal light profile repesentation. At this 


time the only method implemented is Hermite interpolation. Hence, the value of base should 
always be set to miLP_BASIS_HERMITE. 


quality describes the quality of the internal representation of the light profile. For Hermite bases 
the only allowed values are 1 or 3, corresponding to linear of cubic Hermite interpolation. 


filename specifies the file containing the light profile data. 


n_vert_angles gives the number of equidistant vertical angle values to be used for the internal 
representation of the light profile. 


n_horz_angles gives the number of equidistant horizontal angle values to be used for the internal 
representation of the light profile. 


flags IES light profiles are often stored in a non-standard way with respect to the orientation of 
the involved horizontal angles. If flags is set to 1, then mental ray assumes that the horizontal 
angles are stored in non-standard clockwise order. If the flag value is 2, then mental ray assumes 
that the horizontal angles are stored in counter-clockwise order. 


Chapter 5 


Integration of mental ray 


This chapter describes the library version of mental ray, called raylib. None of the material in 
this chapter is relevant to rendering with mental ray, or using a standalone version of mental ray 
or a version that is already integrated into a client application. This chapter is useful only for 
application developers. 


In its library form, mental ray can be integrated into client applications that provide a graphical 
front-end, and also implement modeling and animation functionality. Such applications can use 
raylib to 


e render modeled scenes and animations to images, 


e tessellate scenes or parts of scenes into triangles or wireframe models, which can then 
displayed in realtime using the system’s graphics hardware, 


e visualize shaders in realtime, 


e make use of raylib’s multithreaded and networked Virtual Shared Database for scene 
storage, 


e read and write scenes in the standard scene exchange file format, called the .mi format. 
Converters exist that convert scenes in a wide variety of formats to the .mi format. 


In principle, raylib offers all functionality that is available in the standalone mental ray executable. 
In fact, mental ray itself is a small front-end to raylib that only handles command-line parsing and 
licensing. The Examples chapter will describe a miniature standalone rendering program based 
on raylib. For a description of the mental ray standalone executable and its general feature set, 
refer to “Rendering with mental ray” [Driemeyer 05]. 


This document relies heavily on the preceding shader chapters, which contain the geometry 
shader API of raylib. Geometry shaders are plug-in functions that can procedurally create scene 
elements such as geometric objects. Essentially, this includes all functions required to create a 
scene database. When integrating raylib into a client application, most of the integration work 
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involves converting the internal, time-dynamic representation of the scene in the application 
into the static, frame-by-frame scene representation of raylib. This is done by fully creating the 
scene in the raylib database once (a process called translation), and from that point on using 
incremental changes to modify the scene from frame to frame. All this is identical to what a 
geometry shader does — creating and modifying the scene database. Hence, this document only 
discusses the extensions of the raylib call interface that permit its integration into the client 
application, omitting the scene database API. 


The name of the raylib library is libray.so on Unix systems and libray.d11 on Windows NT 
systems. Three include files are required: 


shader.h 
is the standard shader interface. It must be included because it contains definitions 
of the basic raylib data types such as miVector and miBoolean. 


geoshader.h 
is the geometry shader interface. It contains the mi_api_* API functions and scene 
data type declarations required for building a scene in raylib’s database. 


mirelay.h 
contains the remaining calls required for integrating raylib in a client application, 
beyond the geometry shader functions in geoshader .h. 


Code that links with raylib should not also link with shader. lib like shaders do, because shader. lib 
contains only the strict subset of functions needed by shaders but not the integration API 
functions. This can lead to undefined symbols such as mi_api_render_params. 


Note that all functions and macros provided by raylib begin with the prefix mz. Macros are 
all-uppercase after the mi prefix, except where a C function was implemented as a macro for 
performance reasons. Typedefs begin with a capital letter after the mz prefix, and continue with 
lower case. C functions are all-lowercase. 


On SGI machines, there is a mechanism called “quickstarting” that pre-evaluates linking 
information, which can greatly speed up loading shared objects such as libray.so. If libray.so 
has been replaced with another version, it is possible that the run-time linker rld reports 
unresolved symbols because the pre-linking cache no longer agrees with the library. This may 
be cured by re-quickstarting the executable that raylib.so is linked into, using a command like 
rqs -f execname. Make sure that the directory where libray.so can be found is in the LD_ 
LIBRARY_PATH when re-quickstarting the executable. 


This document describes raylib version 2.1 only. raylib 2.0 is similar but lacks the mi_rc_run 
function, which greatly simplifies tessellation and rendering. 
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5.1 Startup and Shutdown 


5.1.1 Startup 


Before the API module can be used, the following minimal functions must be called to initialize 
the library: 


if (!mi_raylib_attach_process()) 
abort () ; 
mi_mem_init() ; 
mi_ntlib_init(); 
if (!(nthreads = mi_raylib_license_get (mi_msg_no_of_cpus()))) 
abort () ; 
mi_raylib_init(miFALSE, nthreads, coremode) ; 
#ifdef WIN_NT 
mi_link_set_module_handle (GetModuleHandle("libray.d11")) ; 
#endif 


Almost all initialization is done by mi_raylib_init, but some configurations of the library require 
early initialization of some modules to allow licensing or command line parsing, and for the 
function that obtains the number of threads. 


mi_raylib_attach_process 
This function must always be called first before any other raylib function is called. It 
allocates resources such as thread storage that is required to use raylib. If allocation 
fails, it returns miFALSE. 


mi_mem_init 
This function starts up mental ray’s memory manager. It is not part of mi_raylib_init 
because that function requires certain arguments that might be retrieved from the 
command line, and it is useful to be able to call functions such as mi_mem_strdup 
for this purpose. mimem_init must be called before any other mimem_* function 
can work. 


mi_ntlib_init 

This function serves a similar purpose as the previous. mental ray is available on 
a large number of platforms, from PCs to supercomputers, and relies on industry 
standards such as Posix that are available on all of them. Windows NIT, as an 
exception, lacks a few of these functions, so replacements are built into the NT 
version of mental ray. These replacements must be initialized with mi_nthb_init. 
Define WIN_NT on the compiler command line to make this work (note that 
mirelay.h also contains an ifdef WIN_NT). 


At this point the code may perform operations to parse command lines or otherwise obtain 
parameters. MEM functions are now available, but API, SCENE, DB, and the other groups do 
not work yet. The mental ray standalone executable parses the command line into static copies 
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of data structures such as miOptions and miCamera here, which are later installed in the scene 
database after raylib is fully initialized. 


mi_raylib_license_get 

This function obtains the requested number of licenses, and returns the number of 
licenses that were available, which may range from zero to the number requested. 
Each thread requires one license (the actual license policy is built into raylib). If no 
licenses could be obtained, the code cannot proceed and aborts. Here, the number 
of licenses to ask for is taken from mi_msg_no_of_cpus, which returns the number 
of CPUs built into the local machine, but the number of threads can be taken from 
other sources. 


mi_raylib_init 

This function initializes all the rest of raylib. The first argument must always be 
miFALSE. The second is the number of threads, which must be the value returned 
by m1_raylib_license_get (otherwise raylib will not work), and the third can be set 
to miTRUE to prevent raylib from installing a process-wide exception handler that 
catches signals such as bus errors. After this call, all other functions are available. 
This function can only be called once; it is not possible to shut down with mi_raylib- 
exit and then restart. 


mi_link_set-module_handle 

This function is required only on Windows NT. Since raylib is a DLL which loads 
other DLLs that contain shaders, these other DLLs cannot call raylib functions 
without being told raylib’s handle. The handle can be obtained with the Windows 
NT function GetModuleHandle, given the name of the raylib DLL. mental ray 
will pass on the handle to the shader.1ib stubs built into all shader DLLs that 
are loaded later, which allows the shaders to find raylib shader interface functions. 
The default is GetModuleHandle(NULL), that is, the calling executable — which is 
probably not correct because the executable does not contain a shader call interface, 
raylib does. mi_link_set_-module handle is not built into mi_raylib_init because raylib 
integrators may want to change the library name, and because it is a Windows NT- 
only function. Unix has more sophisticated symbol management and does not need 
explicit handles or shader.1lib stubs, so mi_link_set_-module_handle does nothing 
there. 


This was the minimal initialization sequence. After attaching the process, applications will 
normally need to register error handlers and read the standard startup file (rayrc). Here is 
an extended version: 


static void memerror(void) { mi_fatal("out of memory"); } 
static void imgerror(miImg_file * const ifp) 
{ mi_error("file error"); } 

static void error_handler( 

const int errmask, 

const char *const fullmsg, 

const char *const rawmsg, 

const int code) 
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printf("%s\n", fullmsg) ; 


} 


main() 


{ 


if (!mi_raylib_attach_process()) 


abort () ; 


mi_mem_error_handler(memerror) ; 
mi_img_err_handler(imgerror) ; 
mi_errorhandler(error_handler) ; 
mi_mem_init() ; 


mi_mem_error_handler 


This function installs a callback that is called by raylib when a memory allocation 
fails. If there is no callback, this condition is fatal and raylib exits. Installing a callback 
protects the application that raylib is built into by giving it a chance to clean up, 
perhaps freeing memory or giving the user a way out, or doing an emergency save. 
raylib will then only exit if the allocation failed 100 times in a row despite the 


callback. 


miimg_error_handler 


If an image file such as a texture cannot be found or written to, this is a fatal error. 
Installing an image callback gives the application a way to downgrade the error 
level, as was done in the above example. The callback may also be empty; other 
messages with details are printed by raylib first. 


m1i_errorhandler 


This function installs a generic message callback that allows applications to redirect 
all raylib messages (fatal, error, warning, info, progress, debug, and verbose debug) 
to another medium, such as an application error log or popup windows. If there is 
no callback, messages are printed to the terminal window using stderr, if available. 
Messages from server hosts are also redirected. 


After these calls, the initialization can proceed with mimem_init and the remaining calls from 
the first example. 


5.1.2 Shutdown 


When the application terminates, or unloads raylib, it must first shut down the library with the 
following call sequence: 


mi_raylib_license_release() ; 
mi_raylib_exit() ; 
mi_raylib_detach_process() ; 
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mi_raylib_license_release 
This function releases all licenses. No licensed operation, such as tessellation or 
rendering, is possible after this point. 


mi_raylib_exit 
This function shuts down all of raylib. No raylib function other than mi_raylib_ 
detach process may be called after this point. 


mi_raylib_detach process 
This function detaches the raylib library, but does not actually unload it. Unloading 
must be done by the caller, using operating system functions. The mi_link_file- 
remove function may not be used because it only applies to shaders, and because 
raylib was already shut down. 


Note that mental ray cannot be shut down and re-initialized in the same address space image. 
Shutdown must always be followed by unloading raylib. 


5-2 Examples 


This chapter discusses sample code that uses raylib for various purposes. 


5.2.1 Standalone .mi File Renderer 


The following code implements a miniature version of the mental ray standalone executable: 


#include <stdio.h> 
#include <shader.h> 
#include <geoshader.h> 
#include <mirelay.h> 


Static void memerror(void) ‘{ mi_fatal("out of memory"); } 
static void imgerror(miImg_file * const ifp) 


{ mi_fatal("file error, exiting."); } 


int main( 


int argc, 
char *xargv[]) 
{ 
int nthreads; 
miBoolean resume = miFALSE; 


if (!mi_raylib_attach_process()) 

return (1); 
mi_mem_error_handler(memerror) ; 
mi_img_err_handler(imgerror) ; 
mi_mem_init(); 
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mi_ntlib_init(); 
nthreads = mi_raylib_license_get (mi_msg_no_of_cpus()) ; 
mi_raylib_init(miFALSE, nthreads, miFALSE) ; 
#ifdef WIN_NT 
mi_link_set_module_handle (GetModuleHandle("libray.d1l1")); 


#endif 


mi_mi_parse_rayrc(0, miFALSE) ; 
while (mi_mi_parse(argv[1], resume, 0, 0, 0, 0, miFALSE, 0)) f{ 


¥ 


miTag root, caminst, cam, opt; 

miilnh_func inh; 

mi_api_render_params(&root, &caminst, &cam, &opt, &inh); 

resume = mi_rc_run(miRENDER_DEFAULT, 0, 0, root, caminst, 
cam, opt, inh); 

mi_api_render_release() ; 

if (!resume) 

break; 


mi_raylib_license_release() ; 
mi_raylib_exit(); 
mi_raylib_detach_process() ; 
return (0) ; 


The initialization and shutdown parts have already been discussed in section 5.1. Four new 
functions were added: 


mi_m1_parse_rayrc 


mi_m1_parse 


This function reads the ray3rc (mental ray 3.x only) startup file or, if it was 
not found, the rayrc startup file, which may contain link, registry, $include 
statements, and other .mi scene language statements that customize the local 
environment. Neither the include path nor the verbosity-override flag are used. 


This function implements the parser frame loop. It will parse the .mi scene file 
argv[1] and stop after each end of a frame definition. (Obviously there should be 
error checking here to make sure that argv[1] is defined.) The first time it is called 
with a resume flag set to miFALSE, which makes it open the scene file, and all later 
calls set resume to miTRUE to tell mz_mi_parse to continue parsing where it left off. 


The include path, filename override, file type override, and verbosity override 
arguments are not used. The function to read characters from the scene file defaults 
to a builtin getc, and there is no frame callback. (Passing the system getc here can 
cause problems on Windows, which has poor Posix stream support.) 


mi_api_render_params 


mi_rc_run 


This function picks up the root group, camera instance, camera, and options tags 
and the global inheritance or traversal°:! function from the scene. 


This function performs preprocessing, tessellation, rendering, postprocessing, and 
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all other operations necessary for rendering an image, and saves it to disk if the 
scene file contains the appropriate statements. 


5.2.2 Creating and Rendering Polygons with API 


This example is similar to the previous, but the scene is not read from a .mi file but created from 
API calls. Most of these API calls belong to the geometry shader interface described in [PROG]. 
The mainline program is unchanged from the previous example, except that the mi_mi_parse loop 
was replaced with a new function create_scene that uses API calls to create the scene. 


#include <stdio.h> 
#include <shader.h> 
#include <geoshader.h> 
#include <mirelay.h> 


static void memerror(void) { mi_fatal("out of memory"); } 
static void imgerror(miImg_file * const ifp) 

{ mi_fatal("file error, exiting."); } 
static void create_scene(void) ; 


int main( 
int argc , 
char *argv [] ) 
{ 
int nthreads; 
miTag root, caminst, cam, opt; 
miInh_func inh; 


if (!mi_raylib_attach_process()) 
return(1) ; 
mi_mem_error_handler(memerror) ; 
mi_img_err_handler(imgerror) ; 
mi_mem_init() ; 
mi_ntlib_init() ; 
nthreads = mi_raylib_license_get (mi_msg_no_of_cpus()); 
mi_raylib_init(miFALSE, nthreads, miFALSE) ; 
#ifdef WIN_NT 
mi_link_set_module_handle(GetModuleHandle("libray.d11")) ; 
#endif 
mi_mi_parse_rayrc(0, miFALSE) ; 


create_scene(); 

mi_api_render_params(&root, &caminst, &cam, kopt, &inh); 

if (!mi_rc_run(miRENDER_DEFAULT, 0, 0, root, caminst, cam, opt, inh)) 
mi_api_render_release() ; 

mi_raylib_license_release() ; 

mi_raylib_exit(); 

mi_raylib_detach_process() ; 

return(0) ; 


5.2 Examples 


/ 


* 


* the following code was generated from the cube .mi scene using the 
and heavily cleaned up by hand. 


* mitoapi utility, 


*/ 


static miGeoVector cubevectors[8] = { 


{ -0.5, -0.5, -0 
{ -0.5, -0.5, 0. 
{ -0.5, 0.5, -0. 
{ -0.5, 0.5, 0. 
{ 0.5, -0.5, -0. 
{ 0.5, -0.5, 0. 
{ 0.5, 0.5, -0. 
{ @.8. 6.8, 
{ 0, 1, 3, 2}, 
{ 4, Sy; Ty Bs; 
{ 8, 4, 6, T }, 
{ 4, 0, 2, 6 }, 
i ae ee es oe oe 
_ 2, 8, 7, 6 }}: 


static void create_s 


{ 


miCamera 
miOptions 
miLight 
miMaterial 
miInstance 
miQbject 
miParameter 
miFunction_decl 
miTag 
miMatrix 
char 

int 

float 

int 


mi_set_verbosity(miERR_DEFAULT | miERR_INFO | miERR_PROGRESS) ; 
mi_link _file_add("base.so", miFALSE, miFALSE, miFALSE) ; 


/* 
* declare shade 


* / 


symbol = mi_mem_ 
parm = mi_api_parameter_decl(miTYPE_COLOR, symbol, 0); 


plist = parn; 
symbol 


mi_mem_ 


cene (void) 


*camera; 

*options ; 

*light ; 

*material; 

*instance, dummy_inst; 
*object ; 

*parm, *Cparm, *plist; 
*decl, dummy_decl; 
function; 

transform; 

*symbol ; 

ivalue; 

fvalue; 

Le 


r mib_light_point 


strdup("color") ; 


strdup ("shadow") ; 
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parm 
plist 
symbol 
parm 
plist 
symbol 
parm 
plist 
symbol 
parm 
plist 
symbol 
parm 
plist 


symbol 
parm 
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= mi_api_parameter_decl(miTYPE_BOOLEAN, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 

= mi_mem_strdup("factor") ; 

= mi_api_parameter_decl(miTYPE_SCALAR, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 

= mi_mem_strdup("atten") ; 

= mi_api_parameter_decl(miTYPE_BOOLEAN, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 

= mi_mem_strdup("start") ; 

= mi_api_parameter_decl(miTYPE_SCALAR, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 

= mi_mem_strdup("stop") ; 

= mi_api_parameter_decl(miTYPE_SCALAR, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 


= mi_mem_strdup("mib_light_point") ; 
= mi_api_parameter_decl(miTYPE_COLOR, 0, 0); 


if (!(decl = mi_api_funcdecl_begin(parm, symbol, plist) )) 


decl = &dummy_decl; 


decl->version = 1; 
decl->apply = miAPPLY_LIGHT; 


mi_api_ 


/* 


funcdecl_end() ; 


* declare shader mib_illum_phong 


* / 


symbol 
parm 
plist 
symbol 
parm 
plist 
symbol 
parm 
plist 
symbol 
parm 
plist 
symbol 
parm 
plist 
symbol 
parm 
plist 
symbol 
cparm 
parm 


mi_api_ 


plist 


symbol 
parm 


= mi_mem_strdup("ambience") ; 

= mi_api_parameter_decl(miTYPE_COLOR, symbol, 0); 
= parm; 

= mi_mem_strdup("ambient") ; 

= mi_api_parameter_decl(miTYPE_COLOR, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 

= mi_mem_strdup("diffuse") ; 

= mi_api_parameter_decl(miTYPE_COLOR, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 

= mi_mem_strdup("specular") ; 

= mi_api_parameter_decl(miTYPE_COLOR, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 

= mi_mem_strdup("exponent") ; 

= mi_api_parameter_decl(miTYPE_SCALAR, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 

= mi_mem_strdup("mode") ; 

= mi_api_parameter_decl(miTYPE_INTEGER, symbol, 0); 
= mi_api_parameter_append(plist, parm) ; 

= mi_mem_strdup("lights") ; 

= mi_api_parameter_decl(miTYPE_LIGHT, symbol, 0); 
= mi_api_parameter_decl(miTYPE_ARRAY, 0, 0); 
parameter_child(parm, cparm) ; 

= mi_api_parameter_append(plist, parm) ; 


= mi_mem_strdup("mib_illum_phong") ; 
= mi_api_parameter_decl(miTYPE_COLOR, 0, 0); 
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if (!(decl = mi_api_funcdecl_begin(parm, symbol, plist))) 
decl = &dummy_decl; 

decl->version = 2; 

mi_api_funcdecl_end() ; 


/* 
* create options block 


* / 


options = mi_api_options_begin(mi_mem_strdup("opt")) ; 
options->min_samples = -1; 

options->max_samples = 2; 

options->diagnostic_mode &= ~miSCENE_DIAG_SAMPLES ; 
options->contrast.r = 

options->contrast.g 
options->contrast.b 
options->contrast.a = 0.1; 
options->render_space = ’0’; 
mi_api_options_end() ; 


/* 
* create camera 


* / 


camera = mi_api_camera_begin(mi_mem_strdup("cam") ) ; 
camera->frame = 1; 

camera->frame_time = 0; 

camera->frame_field = 0; 
mi_api_function_delete(&camera->output) ; 

camera->output = mi_api_function_append(camera->output, 


mi_api_output_file_def(0, 0, mi_mem_strdup("rgb") , 
mi_mem_strdup("out.rgb"))) ; 


camera->focal = 50; 
camera->orthographic = miFALSE; 
camera->aperture = 44; 
Ccamera->aspect = 1.25; 
camera->x_resolution = 720; 
camera->y_resolution = 576; 
mi_api_camera_end() ; 


/* 
* create camera instance 


*/ 


instance = mi_api_instance_begin(mi_mem_strdup("cam_inst") ) ; 
if (!instance) 
instance = &dummy_inst; 
transform[ 0] = 0.771900; 
transform[ 1] = 0.304200; 
transform[ 2] = -0.558200; 


transform[ 3] = 0.000000; 
transform[ 4] = 0.000000; 
transform[ 5] = 0.878100; 
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transform[ 6] = 0.478500; 
transform[ 7] = 0.000000; 
transform[ 8] = 0.635700; 
transform[ 9] = -0.369300; 
transform[10] = 0.677800; 
transform[1i] = 0.000000; 
transform[12] = 0.000000; 
transform[13] = 0.000000; 
transform[14] = -2.500000; 
transform[15] = .000000; 
instance->tf.function = 0; 


| 
= 


mi_matrix_copy(instance->tf.global_to_local, transform) ; 


if (!mi_matrix_invert (instance->tf.local_to_global, 
instance->tf.global_to_local)) { 


5 


mi_api_warning("singular matrix, using identity") ; 


mi_matrix_ident (instance->tf.global_to_local) ; 
mi_matrix_ident (instance->tf.local_to_global) ; 


} 


mi_api_instance_end(mi_mem_strdup("cam"), 0, (miTag)-1); 


/* 
* create light shader 


* / 
mi_api_function_call(mi_mem_strdup("mib_light_point")) ; 


fvalue = 1.0; 
mi_api_parameter_name(mi_mem_strdup("color")) ; 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 


fvalue = 0.75; 
mi_api_parameter_name(mi_mem_strdup("factor")) ; 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 


function = mi_api_function_call_end(0) ; 
/* 
* create light 


* / 


light = mi_api_light_begin(mi_mem_strdup("light1")) ; 
mi_api_function_delete(&light->shader) ; 
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light->shader = mi_api_function_append(light->shader, function) ; 


light->origin.x = 
light->origin.y = 
light->origin.z = 0; 
light->type = miLIGHT_ORIGIN; 
mi_api_light_end() ; 


/* 


* create light instance 
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* / 


if (instance = mi_api_instance_begin(mi_mem_strdup("lighti_inst"))) { 
instance->tf.global_to_local[12] = -2; 
instance->tf.global_to_local[13] = -3; 
instance->tf.global_to_local [14] 3? 
mi_matrix_invert (instance->tf.local_to_global, 
instance->tf.global_to_local) ; 


} 


mi_api_instance_end(mi_mem_strdup("lighti"), 0, (miTag)-1); 


/* 
* create material shader 


* / 
mi_api_function_call(mi_mem_strdup("mib_illum_phong") ) ; 


fvalue = 0.5; 
mi_api_parameter_name(mi_mem_strdup("ambient") ) ; 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 


fvalue = 0.7; 
mi_api_parameter_name(mi_mem_strdup("diffuse") ) ; 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 


fvalue = 0.3; 
mi_api_parameter_name(mi_mem_strdup("ambience") ) ; 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 


fvalue = 1.0; 
mi_api_parameter_name(mi_mem_strdup("specular")) ; 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 
mi_api_parameter_value(miTYPE_SCALAR, &fvalue, 0, 0); 


ivalue = 50; 
mi_api_parameter_name(mi_mem_strdup("exponent") ) ; 
mi_api_parameter_value(miTYPE_INTEGER, &ivalue, 0, 0); 


ivalue = 1; 
mi_api_parameter_name(mi_mem_strdup ("mode") ) ; 
mi_api_parameter_value(miTYPE_INTEGER, &ivalue, 0, 0); 


mi_api_parameter_name(mi_mem_strdup("lights") ) ; 
mi_api_parameter_push(miTRUE) ; 
mi_api_new_array_element () ; 
mi_api_parameter_value(miTYPE_STRING, 
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mi_mem_strdup("lighti_inst"), 0, 0); 
mi_api_parameter_pop() ; 
function = mi_api_function_call_end(0) ; 


/* 
* create material 


*/ 


material = mi_api_material_begin(mi_mem_strdup("mt1")) ; 
material->opaque = miTRUE; 

material->shader = function; 

mi_api_material_end() ; 


/* 
* create cube object 


* / 


object = mi_api_object_begin(mi_mem_strdup("objecti")) ; 

object->visible = miTRUE; 

object->trace = miTRUE; 

object->shadow = miTRUE; 

object->label = 1; 

mi_api_object_group_begin(0.0); 

for (i=0; i < 8; i++) 
mi_api_geovector_xyz_add(&cubevectors[i]); 

for (i=0; i < 8; i++) 
mi_api_vertex_add(i) ; 

for (i=0; i < 8; it+) { 
mi_api_poly_begin(0O, i ? 0 : mi_mem_strdup("mt1")) ; 
for (j=0; j < 4; j++) 

mi_api_poly_index_add(cubepolygons [i] [j]); 

mi_api_poly_end() ; 

. 

mi_api_object_group_end() ; 

mi_api_object_end() ; 


/* 
* create cube object instance 


+ / 


mi_api_instance_begin(mi_mem_strdup("objecti_inst")) ; 


mi_api_instance_end(mi_mem_strdup("objecti"), 0, (miTag)-1); 


/* 
* create root group containing all instances 


x/ 


mi_api_instgroup_begin(mi_mem_strdup("rootgrp")) ; 
mi_api_instgroup_clear() ; 
mi_api_instgroup_additem(mi_mem_strdup("cam_inst")) ; 
mi_api_instgroup_additem(mi_mem_strdup("light1_inst")) ; 
mi_api_instgroup_additem(mi_mem_strdup("objecti_inst")) ; 
mi_api_instgroup_end() ; 
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/* 
* what to render 


* / 


mi_api_render(mi_mem_strdup("rootgrp"), 
mi_mem_strdup("cam_inst"), 
mi_mem_strdup("opt"), 0); 


All functions used in create_scene are part of the geometry shader API, with three exceptions: 


mi_set_verbosity 
This function sets the verbosity level to a bitmask. It is used here to add two more 
verbosity levels that print informational and progress messages. 


mi_tlink_fileadd 
This function loads a shader library, in this case base .so which implements the light 
shader mib_light_point and the material shader mibillum_phong. Note that this 1s 
not a mi_api_* function and hence does not require that its argument is an allocated 
string, so mi_mem_strdup is not used here. 


mi_api_render 
This function accepts the names of the root group, the camera instance, the camera, 
and the inheritance or traversal?! function, and stores them in a place where they 
can be picked up with mi_api_render_params. 


Here is the .mi scene file that create_scene was derived from. Feeding this scene to the first example 
using mi_mi_parse will create exactly the same rendered image as this example. 


verbose on 
link "base.so" 


declare shader 
color "mib_light_point" ( 


color "cOoLor” . 
boolean "Shadow", 
scalar "Tactor"™ , 
boolean "atten", 
scalar "SUAr s 
scalar "stop" 


) 

version 1 

apply light 
end declare 


declare shader 
color "mib_illum_phong" ( 
color "ambience", 
color "ambient", 


586 5 Integration of mental ray 


color "“dittTuse" ; 


color "specular", 
scalar "exponent", 
integer "mode", 
array light "lights" 


) 
version 2 
end declare 


options "opt" 
samples a 
contrast 0.1 O.1 O.1 
object space 

end options 


camera "cam" 


frame 1 

output "rgb" “out .rgb" 
focal 50 

aperture 2S 

aspect 1.26 
resolution 720 576 


end camera 


instance "cam_inst" "cam" 
transform 0.7719. 0.3042 -0.5582 0.0 
0.0000 0.8781 0.4785 0.0 
0.6357 -0.3693 0.6778 0.0 
0.0000 0.0000 -2.5000 1.0 


end instance 


light "light1" 
"mib_light_point" ( 


"color" : ee 
"factor" 0.75 
) 
origin 000 
end light 


instance "lighti_inst" "light1i" 


transform 1 0 0 O 
Oo t+ 0 8 
0 0 1 0 
-2 a we. 2 


end instance 


material "mtl" 
opaque 
"mib_illum_phong" ( 
"ambient" 0.5 
"diffuse" ew 4 
"ambience" 0.3 
"specular" 1.0 


He © oO © 


OWN oO 
eK © O Oo 


OWN oO 
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"exponent" 50, 

"mode" 1, 

“Lights” ["dightiainet"| 
) 


end material 


object "objecti" 
visible trace shadow 


tag 1 
group 
“0.06 “0.6. ~O.5 
“0.5 “0.5: 0.5 
“0.8 0.6 -G.5 
“0.5 O.5 0.5 
VU. "0.8 -O.6 
0.5 -0.5 0.5 
0.56 0.5 -0.5 
0.56 0.6 0.5 
¥O wil v2 ‘3 
v4 v5 v6 v7 
p “mel” GO 1 8 2 
p 1 & Ff 3 
Pp 5 4 6 7 
Pp 4 0 2 6 
P 4 5 1 0 
p 23 f & 
end group 
end object 


instance "objecti_inst" "objecti" 
transform 1 0 0 


oOo Or © 


0 0 0 
0 1 O 
0 Gu. 
end instance 
instgroup "rootgrp" 
"cam_inst" "light1i_inst" "objecti_inst" 


end instgroup 


render "rootgrp" "cam_inst" "opt" 


5.2.3 Creating and Rendering Free-Form Surfaces with API 


This example is similar to the previous, except that it creates a free-form surface object. The main 
function is unchanged, as are the beginning and end of create_scene function. Omitted parts are 
indicated by “...” and should be filled in from the previous example. 
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* the following code was generated from the cube .mi scene using the 


* mitoapi utility, and heavily cleaned up by hand. 


* / 


static miGeoVector cpoint[] 


iz 


struct { int pointref; double 
Oh. By. 


Fy 


static void 


{ 


HAA AA AAA AAA AAA AAA AHA AAA AAA 


AAA AA AAA AAA 


Oro CO CO OCOCOrFCm rhc RP CUCOCUCOCUC OUC OCU COCcrRRD RLU FPR LUC OUCUCOUCUCOUCOUCOOCUCUrRRMhBHDUCO 


=s 
o1 
Breer PP BP PPP RP 


Oo o 2 o ao 2 oOo oo 6 6 2 & 


“ “ “ “ “ “ “ “ 


WY OY OY OY 


.500000, O. 
000000, 
.000000, 
.500000, 
000000, 
000000, 
000000, 
.500000, 
000000, 
.000000, 
.000000, 
.500000, 
.000000, 
000000, 
.000000, 
.500000, 
000000, 
000000, 
000000, 
.500000, 
000000, 
000000, 
000000, 
.500000, 
000000, 
.500000, 


0. 
1.000000, 
1.000000, 
1.000000, 
0.500000, 
0.000000, 
0.000000, 
0.000000, 
0.500000, 
1.000000, 
1.000000, 
1.000000, 
0.500000, 
0. 
0 
0 
0 
1 
1 
1 
0 
0 
0 
0 
0 


500000, 
500000, 


000000, 


.000000, 
000000, 
.500000, 
000000, 
.000000, 
000000, 
.500000, 
000000, 
.000000, 
000000, 
.500000, 


0, 
0, 
1, 
5; 
1, 
12, 
16, 
19, 
235 
20 
20% 


AAA AA AAA AAA 


1. 


RFrRDONNON FF KF FE 


ik 


0.000000 
0.000000 
0.000000 
0.000000 
0.000000 
0.000000 
0.000000 
0.000000 
0.000000 
0.500000 
0.500000 
D. 
0 
0 
0 
0 
0 
1 
1 
1 
1 
1 
1 
| 
| 
1 


500000 


. 500000 
. 500000 
. 500000 
. 500000 
. 500000 
. 000000 
. 000000 
. 000000 
. 000000 
. 000000 
. 000000 
. 000000 
. 000000 
000000 


“ “ “ “ 


J 


“ “ “ 


“ 


eccoooo eo oo Oo 
WMH YY OY YOY OY 


“ 


create_scene (void) 


}; 
Fs 
}, 
}, 
}; 
}, 
ts 
}; 
}, 
i 
}, 
}, 
}; 
ys 
}, 
}, 
}, 
ts 
I 
}, 
as 
}, 
}; 
}; 
}; 
} 


weight ; 


AAA AKA AA AAA 


} paras [] 
0G, 2.0 }, 
0, 2.0 }, 
oA Fs 
ae ee 
9, 2.0 }, 
is, 2.0 3, 
9, 2.0 }, 
20, 1503; 
24, 1.0 }, 
25, 2.0 }, 
95, 2.0 3; 


AANA AAA AAA KH 


FPerRFrPreerRNDNNN KF F&F 
oo oOo © oo oo o.0od © © © 
Ye oe oe oe 


“ 


. 


“ 


“ 


“ 


“ 


“ 
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/* 
* create material 


*/ 


material = mi_api_material_begin(mi_mem_strdup("mt1")) ; 
material->opaque = miTRUE; 

material->shader = function; 

mi_api_material_end() ; 


/* 
* start surface object 
* / 
{ 
miDlist *range ; 
miGeoScalar S; 
miApprox approx; 


object = mi_api_object_begin(mi_mem_strdup("object1i")) ; 
object->visible = miTRUE; 
object->shadow = miTRUE; 


object->trace = miTRUE; 

object->label = 1; 

/* 
* add a rational Bezier basis with degree 2 
*/ 


mi_api_basis_add(mi_mem_strdup("bez2"), miTRUE, miBASIS_BEZIER, 2,0,0); 


/* 
* object group: define 26 vectors, then 26 vertices (control points) 


*/ 


mi_api_object_group_begin(0.0) ; 
for (i=0;. i) < 263. i++) 
mi_api_geovector_xyz_add(&cpoint [i]) ; 
for (i=0; i < 26; i++) 
mi_api_vertex_add(i) ; 


/* 
* define a surface "surf" with U and V parameter vectors (length 5 
* and 3, respectively), and 45 control points 


* / 
mi_api_surface_begin(mi_mem_strdup("surf"), mi_mem_strdup("mt1")) ; 


range = mi_api_dlist_create(miDLIST_GEOSCALAR) ; 
for (i=0, s=0; i < 5; it+, s+=0.25) 
mi_api_dlist_add(range, &s); 
mi_api_surface_params(miU, mi_mem_strdup("bez2") , 
0.0, 1.0, range, miFALSE) ; 
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range = mi_api_dlist_create(miDLIST_GEOSCALAR) ; 
for (i=0, s=0; i < 3; i++, s+=0.5) 
mi_api_dlist_add(range, &s); 
mi_api_surface_params(miV, mi_mem_strdup("bez2"), 
0.0, 1.0, range, miFALSE) ; 
for (i=0; i < 45; i++) 
mi_api_vertex_ref_add(paras[i].pointref, paras[i] .weight) ; 


mi_api_surface_end() ; 


/* 
* set the approximation 


* / 


miAPPROX_DEFAULT (approx) ; 
approx.method = miAPPROX_PARAMETRIC; 
approx.cnst [miCNST_UPARAM] = 6; 
approx.cnst [miCNST_VPARAM] = 6; 


approx. subdiv [miMIN] = 0; 
approx. subdiv [miMAX] = 5; 
approx.max = miHUGE_INT; 
mi_api_surface_approx(mi_mem_strdup("surf"), &approx) ; 
/* 

* finish object group and object 

* / 


mi_api_object_group_end() ; 
mi_api_object_end() ; 


J 


/* 
* create object instance 


* / 


if (instance = mi_api_instance_begin(mi_mem_strdup("objecti_inst"))) { 
instance->tf.global_to_local[12] = 0.93; 
instance->tf.global_to_local[13] = 0.13; 
mi_matrix_invert (instance->tf.local_to_global, 
instance->tf.global_to_local) ; 


J 
mi_api_instance_end(mi_mem_strdup("objecti"), 0, (miTag)-1); 
/* 

* create root group containing all instances 

*/ 


The create_scene fragment above is equivalent to the following .mi scene language fragment: 
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object "spherei" visible shadow trace tag 1 
basis "bez2" rational bezier 2 


group 
0.5 0.5 0.0 i«0 0,8 9.9 1:0 1.9 6.0 
0.5 2.0 9.0 0.0. 1.9 0.0 0.0 0.5 0.0 
0.0 0.0 0.0 0.5 .0.0 0.0 1,8 0.0 0.0 
LY O.5- 0.46 LO Lak 28 0.5 1.0 0.5 
C0: 134) “OLS oo Ge YS 0.0 0.0 0.5 
v.58 0.0 0.5 L.0 O.0 05 10 O35 1,9 
120° 3,0 ° (2.0 vio 238° 2.0 Oa 1.0° 2.0 
Oo OS 2.0 O.0 (8.0 'T.9 055 U0 1.8 
LO O50" 2.9 0.56 0.5 1.0 
VTUViwvy2vsvavsy¥67 (4 6 ¥' 9 v 10 


y ilwvwi2gwvwi3svi4¥ 15¥v¥i1i6s¥ iif v is v 19 
vy 20 vy 21 v 22 v 23 vv 24 v 25 


surface "surf" 


"“pezz" 0.0 1.0 0.0 0.25 0.5 0.75 1.0 
"bez2" 0.0 1.0 0.0 0.5 1.0 

0 ) Ow 2 0) 0 

0 Ow 2 0) 0 1 

2 3 Ww 2 4 5 6 
7Tw2 8 1 Sw 2 1 ws 
11 w4 12w2 13Ww2 14W2 15w0 4 
16 w 2 9uv2 17 18 19 w 2 
20 21 22 23 w2 24 

17 25 25 25.0 2° 25 

25 25 2zow2 25 20 


approximate surface parametric 6 6 "surf" 
end group 
end object 


instance "objecti_inst" "objecti" 


transform i 6) ) ) 
0) 1 ) ) 
0) 0 1 0) 
0.93..0.13 0 1 


end instance 


5.2.4 Incremental Interactive Pixel Previewing 


Pixel previewing is a way of rendering a frame several times in sequence, with only shader 
parameters changing. It is intended for graphical front-ends that allow the user to tune shader 
parameters such as object colors with maximum turnaround. 


For this purpose, raylib supports a preview mode that retains the frame buffers between successive 
frames, and collects information about which shaders have contributed to which pixels. When 
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the next frame is rendered, a shader bitmap can be passed that tells raylib which shaders have 
changed parameters. It then re-renders only those pixels that are affected, and leaves all other 
pixels unchanged. If a screen sub-rectangle contains no changed pixels, the entire rectangle 1s 
omitted. 


This works for all types of shader changes except those affecting geometry (geometry and 
displacement shaders), and except output shaders. (Tuning output shaders requires no re- 
rendering at all; this case is handled with mui_rc_run’s miRENDER_FB_* modes.) Pixel previewing 
does, however, work with full ray tracing (transparency, reflectivity, volumes, etc). In principle, 
it also works with global illumination and lens shaders, but there is usually little benefit because 
these shaders tend to touch all or most pixels. 


The standard sequence of steps for pixel previewing is 
1. turn pixel previewing on in the options block. 


2. call mi_rc_run to preprocess, create shadow maps, and render (and optionally run output 


shaders). 


3. perform an incremental change to shader parameters, and record the label of the changed 


shader. 


4. call mi_rc_run to preprocess and render. 

5. repeat steps 3 and 4. 

6. turn pixel previewing off in the options block. 
7. call mi_rc_run to postprocess. 


Shader labels are assigned by raylib when shaders are created. Step 3 is expected to create the 
changed-shader bitmap by reading the miFunction’s label field. If the label is , bit (7 % 31) of 
the bitmap should be set. Since the bitmap has only 32 bits it is possible that too many pixels are 
rerendered, but never too few. To avoid accidentally hitting the bit of the lens shader, it may be a 
good idea to disable lens and atmosphere shaders in the options block. 


The following example uses pixel previewing to render a scene with two cubes, a large cyan one 
and a small magenta one in front, then changes the magenta color to yellow, and rerenders. Only 
magenta pixels will be rerendered. The initialization code up to and including the call to mi_mi_ 
parse_rayrc is identical to the previous examples. 


mi_mi_parse_rayrc(0, miFALSE) ; 

if (!mi_mi_parse(argv[1], miFALSE, 0, 0, 0, 0, miFALSE, 0)) 
mi_fatal("parse error") ; 

mi_api_render_params(&root, &caminst, &cam, &opt, &inh) ; 


/* 


* turn pixel previewing on 
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* / 
((mi0ptions *)mi_scene_edit (opt) )->pixel_preview = miTRUE; 
mi_scene_edit_end (opt) ; 


/* 
* render first frame, standard magenta cube (mt12) 
* / 
if (!mi_rc_run(miRENDER_PREPROC | miRENDER_OBJ_DELETE | 
miRENDER_SHADOWMAP | miRENDER_DISPLAY | 
miRENDER_RENDER, 0, 0, root, caminst, cam, opt, inh)) 
mi_fatal("render error"); 
/* 
* incremental change: change magenta to yellow 
* / 


mtl_tag = mi_api_name_lookup(mi_mem_strdup("mt12")) ; 


mtl = (miMaterial *)mi_db_access(mtl_tag) ; 
func = (miFunction *)mi_scene_edit (mtl->shader) ; 
label = func->label; 


mi_api_parameter_lookup(&type, &is_array, offset, 
func->function_decl, miFALSE, 
mi_mem_strdup("ambient") ) ; 

miColor *amb = (miColor *)(func->parameters + offset) ; 


mi_api_parameter_lookup(&type, &is_array, offset, 
func->function_decl, miFALSE, 
mi_mem_strdup("diffuse") ) ; 

miColor *dif = (miColor *)(func->parameters + offset) ; 


amb->r = dif->r = 0.8; 
amb->g = dif->g = 0.8; 
amb->b = dif->b = QO; 


5 


mi_scene_edit_end(mtl->shader) ; 
mi_db_unpin(mtl_tag) ; 


/* 
* render again (only magenta pixels will be rerendered) 
* / 
if (!mi_rc_run(miRENDER_RENDER, 
0, 1 << (label & 31), root, caminst, cam, opt, inh)) 
mi_fatal("render error") ; 


/* 
* turn pixel previewing off and postprocess (to delete frame bufs) 
* / 
((miOptions *)mi_scene_edit (opt))->pixel_preview = miFALSE; 
mi_scene_edit_end (opt) ; 
if (!mi_rc_run(miRENDER_POSTPROC, 0, 0, root, caminst, cam, opt, inh)) 
mi_fatal("postprocess error") ; 


mi_api_render_release() ; 
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mi_raylib_exit(); 
mi_raylib_detach_process() ; 
return(0) ; 


Note that the method to change the shader parameters is rather inflexible — it makes assumptions 
about where to find the ambient and diffuse colors in the shader parameter block rather than 
properly computing the offsets. The way it is written here probably will not work for shaders 
other than mib_illum_phong. 


The postprocessing call to mi_rc_run at the end of the pixel preview render loop is important 
because it releases the frame buffers and certain bitmap support buffers maintained by raylib for 
previewing. Failure to postprocess introduces a large memory leak. It is important to clear the 
pixel_preview flag in the options block before the postprocessing call. 


To keep the example short, this code reads a scene file whose name must be passed as the first 
command-line argument (argv/1/). This file defines the two instances of a cube, with the front 
cube inheriting the material mt12 that is incrementally changed. Here is the scene file: 


$include <base.mi> 

options "opt" 
samples 0 0 
object space 


end options 


camera "cam" 


output "pic" “out rgb" 
focal 50 
aperture 44 


end camera 


instance "cam_inst" "cam" 
transform 0.7719 0.3042 -0.5582 0.0 
0.0000 0.8781 0.4785 0.0 
0.6357 -0,.3693 0.6778 0.0 
0.0000 0.0000 -2.5000 1.0 
end instance 


light "lighti" 
"mib_light_point" ("color" 1 1 1) 
origin 000 

end light 


instance "lighti_inst" "lighti" 
transform L000 O200 0010 -2.-5 -2 1 
end instance 


material "mtli" "mib_illum_phong" ( 
"ambient" Ui0 O56 O58, 
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ae 


"diffuse" 0.0 0.7 0.7, 
"ambience" 0.3 0.3 0.3, 
"lights" ["light1_inst"]) 


end material 


material "mt12" "mib_illum_phong" ( 


"ambient" 0.5 08.0 0.5, 
"diffuse" o.¥ @.0 0.7, 
"ambience" 0.3 0.3 0.3, 
"lights" ["light1_inst"]) 


end material 


object "cubel" visible trace 
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end group 
end object 
instance "cubel_inst" "cubei" 
material a gt 
transform 1000 01090 0 0 
end instance 
instance "cube2_inst" "cubei" 
material "hel" 
transform 300 0 0600 0 0 


end instance 


instgroup "rootgrp" 
"“cam_inst" "lighti_inst" 
end instgroup 


"cubel_ inst" 


render "rootgrp" "cam_inst" "opt" 


5 -.5 -.5 .5 5 
5 -.5 .5 5 5 
7 & ad 
O26p4510p2376 
1 0 o0 071 
3 0 2-2-2 1 


"cube2_inst" 


When running this example with the zmf_disp utility attached to the output image file out . rgb, 
only the screen subrectangles containing magenta pixels are redisplayed. Cyan pixels are also not 
recomputed but redisplayed because zmf_disp always deals with complete subrectangles. 


5.2.5 Defining Custom Image File Formats 


The miimg_custom_format function allows registering up to 16 new file formats, in addition to 
the file formats already built into raylibsuch as jpg or tif. This requires installing six functions 
in raylib, and passing a number of flags. This example defines a new file format foo, which is both 
the name of the format and the standard file extension (however, it will work with any extension, 
the new name merely establishes the naming convention). 


The format written in this example is Jef Poskanzer’s Portable Pixmap format type P6. Reading 
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additionally supports type P3. The standard name of this format is ppm, but raylib already supports 
this type so anew name had to be chosen for this example. 


The following code can be compiled into a shared library (DSO or DLL) and linked into raylib 
with mi_link_file_add, or with a link statement in the master host’s rayrc startup file. For this 
reason the name of the “mainline” function is module_init — raylib will call this function on 
loading the library, so no explicit call is needed. However, normally this code will reside in the 
client application that raylib is linked into, not a separate library, and mi_img_custom_format may 
be called anywhere after initialization of raylib. 


First, define a data structure that maintains internal information needed during reading and 
writing. Many formats require such temporary data, for things like temporary scanlines for 
compression and decompression, size and scanline counters, and subtype fields. It is not required 
by mental ray, but useful for the custom format code. This data structure is normally allocated 
by the open and create functions, used by the read and write functions, and released by the close 
function. Here, it contains a flag ascii that determines what format is being read (P3 ASCII or P6 
binary), the number of bits per component, and a scanline buffer. 


#include <stdio.h> 
#include <ctype.h> 
#include <errno.h> 
#include <string.h> 
#include <shader.h> 
#include <geoshader.h> 
#include <mirelay.h> 


typedef struct { 


miBoolean ascil; /* read ascii, not binary */ 
int bits; /* source bit length per component */ 
int c: /* last char read from file */ 
miBoolean ok; /* error during ascii reading? */ 
char *buffer; /* RGB scanline buffer */ 

} Ppm_data; 


The next function returns miTRUE if the passed first 256 bytes of the file contain a valid PPM 
header that can be understood by the open function: 


/* 
* return miTRUE if <buf> is a valid ppm header beginning with "P3" for 
* ascii files and "P6" for binary files. 


* / 
miBoolean customimage_test_ppm( 
miImg_file * const Sto, /* open file info */ 
char * const buf ) /* first 256 bytes of file */ 
1 
return(buf [0] == ’P’ && (buf[i] == ’3’ || buf[1] == ’6’)); 
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This is a very simple test function; most will try to check header data for consistency and perhaps 
even whether the file length is correct. False positives prevent all following custom file formats 
from being recognized because mental ray checks all file formats in order, with custom formats 
last. 


The following functions create and open files. The actual file is created and opened by raylib, so 
here we only have to write or read the header, respectively, and allocate the private data block 
Ppm_data. The data block is attached to ifp — fp.p. Note that it should always be allocated using 
MEM functions; static variables are a bad idea because it makes these functions non-reentrant, 
which will lead to difficult and unpredictable bugs. mental ray 3.0, unlike mental ray 2.1, can and 
often does load multiple texture files concurrently. 


A single custom format may handle more than one data type. For example, the create function 
may be changed to handle both 8 and 16 bits per pixel. In this case, it would check ifp — type 
to determine what kind of header to write and how large the private scanline buffer needs to be, 
and the write function described later would write the data in a different format. This can happen 
only if the typemap argument of mi_img_custom_format (see below) has more than one bit set. 
This method is strongly recommended; avoid creating one custom format per data type. 


/* 
* create a ppm P6 file. The header is ascii, the rest binary. The data.p 
* field in ifp is used to attach data used while the file is open. 


* / 

miBoolean customimage_create_ppm( 
miIlmg_ file * const ifp) /* open file info */ 

{ 
Ppm_data *data; 
fprintf((FILE *)ifp->fp.p, "P6\n# created by custom format demo\n") ; 
fprintf( (FILE *)ifp->fp.p, "4d 4d 255\n", ifp->width, ifp->height) ; 
data = (Ppm_data *)mi_mem_allocate(sizeof (Ppm_data) ) ; 
data->ascii = miFALSE; 
data->buffer = (char *)mi_mem_allocate(3 * ifp->width) ; 
ifp->data.p = (void *)data; 
return (miTRUE) ; 

} 

/* 


* open a ppm file for reading. Allocate all data structures and interpret 
* the header. The header is always ascii, the rest is either ascii or binary. 


*/ 
miBoolean customimage_open_ppm( 
miImg file * const ifp, /* open file info */ 
char * const buf ) /* first 256 bytes of file */ 
‘ 
Ppm_data xdata; /* file information */ 
int Gc, /* current char from input file */ 


int field(s}: /* header numbers: width, height, 255*/ 
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int nfield = 0; /* next number to read, 0..2, 3=done */ 


fgetc((FILE *)ifp->fp.p); /* skip magic no */ 
fgetc((FILE *)ifp->fp.p); 
fgetc((FILE *)ifp->fp.p); 


toe.C: 3) 4. 
if (c == °#’) 
do c = fgetc((FILE *)ifp->fp.p); 
while (c != ’\n’ && c != EOF); 
else if (c == ’\n’ && nfield == 3) 
break; 
else if (c ==’ ? || c s= ?\t? [|] ¢ == ’\n? || c = ’\r’) 


c = fgetc((FILE *)ifp->fp.p); 


else if (isdigit(c)) { 
field[nfield] = 0; 
do { 
field[nfield] = field[nfield] * 10 + c - ’0’; 
c = fgetc((FILE *)ifp->fp.p); 
} while (isdigit(c)); 


nfield++; 
} else { 
mi_img_custom_format_error(ifp, miIMG_ERR_DECODE, 0); 
return (miFALSE) ; 
r 
} 
ifp->width = field[0]; 
ifp->height = field[1]; 
ifp->comp = 3; 
lip=->bite = 8; 


data = (Ppm_data *)mi_mem_allocate(sizeof (Ppm_data) ) ; 
data->ascii = buf[i] == ’3’; 


if (field[2] > 255) { 
if ('data->ascii || field[2] > 65535) { 
mi_img_custom_format_error(ifp, miIMG_ERR_SUBTYPE, 0); 
return (miFALSE) ; 
} else 
data->bits = 16; 
} else 
data->bits = 8; 


data->buffer = (char *)mi_mem_allocate(3 * ifp->width) ; 
ifp->data.p = (void *)data; 
return (miTRUE) ; 


Closing the file is simple. Again, the actual file on disk is not closed here, this is done by raylib. 
It is only necessary to release the allocated private data. It is good practice to clear the pointer 
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afterwards to prevent releasing the pointer more than once. 


/* 
* close the ppm file, and release all data structures that have been 
* allocated by the open and create routines. This routine is also called 
* when an open or create failed, to clean up things that have already 
* been successfully allocated. 


*/ 


miBoolean customimage_close_ppm( 
miImg_file * const ifp) 


{ 
if (ifp->data.p) { 
mi_mem_release((char *)((Ppm_data *)ifp->data.p)->buffer) ; 
mi_mem_release((char *)ifp->data.p); 
ifp->data.p = 0; 
: 
return (miTRUE) ; 
t 


The read function reads the next scanline into the /ive buffer maintained by raylib. Its operation 
depends on whether the open function has recognized a P3 or P6 header, and has set the private 
asci flag accordingly. 16-bit ASCII data is scaled back to 8 bits. 


/* 
* read one integer from the file; used by the ascii format. Set the error 
* flag if something unexpected is read. 


* / 

static int read_int( 
miImg_file * const ifp) /* open file */ 

{ 
int n = 0; /* returned int: */ 
miBoolean minus; /* shouldn’t happen */ 
Ppm_data *data = (Ppm_data *)ifp->data.p; 
int c = data->c; 
while (c ==’? || c == ?\t’? || c == ’\n’ || c == ’\r’) 

c = fgetc((FILE *)ifp->fp.p); 


if (minus = c == ’-’) 
c = fgetc((FILE *)ifp->fp.p) ; 

if (lisdigit(c)) { 
mi_img_custom_format_error(ifp, miIMG_ERR_DECODE, 0); 
data->ok = miFALSE; 


} 
while (isdigit(c)) f{ 

n=n * 10 + ¢c = 70’; 

c = fgetc((FILE *)ifp->fp.p); 
} 


if (data->bits > 8) 
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n >>= 8; 
data->c = ¢c; 
return(minus ? 0 : n > 255 ? 255 : n); 


/* 
* read one RGB scanline from the file, either in ascii or binary format 
* NOTE: miIMG_LINEACCESS is deprecated, will disappear in mental ray 3.2! 


* / 
miBoolean customimage_read_ppm( 
miImg file * const it 0, /* open file */ 
miImg_line * const line) /* ptrs to component buffers */ 
{ 
Ppm_data *xdata = (Ppm_data *)ifp->data.p; 
register char *p = data->buffer ; 
register miUchar *r = miIMG_LINEACCESS(line, miIMG_R); 
register miUchar *g = miIMG_LINEACCESS(line, miIMG_G) ; 
register miUchar *b = miIMG_LINEACCESS(line, miIMG_B); 
register int X; 
data->ok = miTRUE; 
if (data->ascii) { 
data->c = ’\n’; 
for (x=ifp=>width; x: x--) { 
*r++ = read_int(ifp); 
*o++ = read_int(ifp) ; 
*b++ = read_int(ifp) ; 
} 
} else { 
if (fread(p, ifp->width, 3, (FILE *)ifp->fp.p) != 3) { 
mi_img_custom_format_error(ifp, miIMG_ERR_READ, errno) ; 
return (miFALSE) ; 
‘; 
for (x=ifp->width; x; x--) { 
r++ = *ptt; 
roe = €prt; 
*b++ = *pt+; 
} 
t 
return (data->ok) ; 
} 


Scanline writing is very similar, except that only one format (binary P6) is supported here. 


/* 
* write one RGB scanline to the file. 


* / 


miBoolean customimage_write_ppm( 
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miImg file * const Sy /* open file */ 
miImg_line * const line) /* ptrs to component buffers */ 
{ 
Ppm_data xdata = (Ppm_data *)ifp->data.p; 
register unsigned char *q = (unsigned char *)data->buffer; 
register miUchar *r = miIMG_LINEACCESS(line, miIMG_R); 
register miUchar *g = miIMG_LINEACCESS (line, miIMG_G) ; 
register miUchar *b = miIMG_LINEACCESS (line, miIMG_B) ; 
register int x5 
for (x=ifp->width; x; x--, q+=3) { 
qlO] = *r++; 
qli] = *gt++; 
ql2] = *b++; 
t 
if (fwrite(data->buffer, ifp->width, 3, (FILE *)ifp->fp.p) != 3) f 
mi_img_custom_format_error(ifp, miIMG_ERR_WRITE, errno) ; 
return (miFALSE) ; 
} 
return (miTRUE) ; 
t 


Finally, the above functions need to be registered with raylib. After registering, the format 1s 
available just like raylib’s built-in formats. The miimg_custom_format function can fail only if an 
illegal format or a null name is passed. 


/* 
*x install the above functions in raylib. The name "module_init" was chosen 
* so this file can be compiled to a library and linked into raylib, since 
* raylib will always call module_init in a library it has just loaded. 


* / 


DLLEXPORT void module_init (void) 
i. 
if (!mi_img_custom_format (mi IMG_FORMAT_CUSTOM_O, 

customimage_test_ppm, 
customimage_create_ppm, 
customimage_open_ppm, 
customimage_close_ppm, 
customimage_read_ppm, 
customimage_write_ppm, 


miTRUE, /* top line first */ 
"foo" . /* standard extension */ 
1 << miIMG_TYPE_RGB, /* allowed types */ 
miIMG_TYPE_RGB, /* preferred data type*/ 
0)) /* always 0 */ 


mi_error("internal error: failed to create foo image format") ; 
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5-3. Call interface 


This chapter lists all function calls that are available in addition to those described in the shader 
interface and geometry shader interface chapters of this book. A few functions were duplicated 
for completeness. 


5-3-1 Tessellation and Rendering (RC) 
#define miRENDER_PREPROC 0x00001 
#define miRENDER_OBJ_DELETE 0x00002 
#define miRENDER_SHADOWMAP 0x00004 
#define miRENDER_DISPLAY 0x00008 
#define miRENDER_RENDER 0x00010 
#define miRENDER_FB_SAVE 0x00020 
#define miRENDER_FB_RESTORE 0x00040 
#define miRENDER_FB_DELETE 0x00080 
#define miRENDER_OUTPUTSH 0x00100 
#define miRENDER_POSTPROC 0x00200 
#define miRENDER_IMAGE_DELETE 0x00400 
#define miRENDER_CHECK 0x00800 
#define miRENDER_DUMP 0x01000 
#define miRENDER_ACCEL_DELETE 0x02000 
#define miRENDER_LIGHTMAP 0x04000 /* mental ray 3.0 or later */ 
#define miRENDER_REINHERIT 0x08000 /* mental ray 3.2 or later */ 
#define miRENDER_POSTPROC_FBC 0x10000 /* mental ray 3.2 or later */ 
#define miRENDER_DISPLAY_FG 0x20000 /* mental ray 3.3 or later */ 
#define miRENDER_RENDER_FG 0x40000 /* mental ray 3.3 or later */ 
#define miRENDER_DEFAULT 0x0471f 
#define miRENDER_SHADOWMAP_ONLY 0x00207 /* mental ray 3.1 or later */ 
miBoolean mi_rc_run( 
miUint mode, 
int imgpipe, 
unsigned int prevmask, 


miTag root_group, 
miTag c_inst_tag, 
miTag camera_tag, 
miTag option_tag, 
miInh_func inh_func) 


This is the main entry point of the renderer. It handles preprocessing, rendering, output shading, 
postprocessing, and realtime image previews. It is basically a wrapper around the main rendering 
engine, and also handles all setup and cleanup. The following arguments must be passed: 

mode A bitmap that enables or disables the various stages of tessellation and 
rendering. See below. The mode bitmap is ignored in cut window mode. 
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imgpipe 


prevmask 


root_group 


c_inst_tag 


camera_tag 
option_tag 


inh_func 
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If set to a nonzero file descriptor, completed image rectangles are sent 
to this file descriptor in a format that the imf_disp tool can display. This 
implements the -imgpipe command-line option of mental ray. It is useful 
for real-time previews of rendering but may slow down rendering in relay 
library applications where the pixel data must be sent across the network. 
This argument is ignored if the mode mask does not specify rendering or 
displaying (miRENDER_RENDER plus miRENDER DISPLAY). 


This mode implements pixel previewing, if enabled by the preview_mode 
flag in the options block. It is a 32-bit mask that specifies which shaders have 
changed their parameters since the scene was last rendered. Each shader has 
a label field in its miFunction definition, which determines the bit position 
in prevmask, modulo 32. For example, if the parameters of shaders 10, 42, 
and 117 changed, then bits 10 (10 and 42 module 32) and 21 (117 modulo 32) 
must be set in preumask. The renderer uses this information to determine 
which pixels must be rerendered. If pixel previewing is not enabled, or if the 
mode mask does not specify rendering, 0 should be passed. 


The tag of the root group of the scene. This and the following four arguments 
can be obtained from the mi_api_render_params function, which picks them 


up from a previous m1_api_render call. 


The tag of the camera instance of the scene. It must be present in the root 
group also. 


The tag of the camera of the scene. 
The tag of the options of the scene. 
The inheritance function of the scene, or 0 if there is none. If the inh_is_ 


traversal’! field in the options is set, inh_func is the traversal function*" 
instead of the inheritance function. 


The following bits may be added to form the mode argument: 
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miRENDER_PREPROC scene preprocessing 
miRENDER_OBJ_DELETE delete source geometry 
miRENDER_SHADOWMAP render shadow maps 
miRENDER_DISPLAY connect to imf_disp or imgpipe 
miRENDER_DISPLAY_FG°” sub-mode, shows coarse final gather progress 
miRENDER_RENDER render 
miRENDER_RENDER_FG>? create finalgather map only 
miRENDER_FB_SAVE make a copy of the frame buffers 
miRENDER_FB_RESTORE restore frame buffer copy 
miRENDER_FB_DELETE delete frame buffer copy 
miRENDER_OUTPUTSH call output shaders 
miRENDER_POSTPROC scene postprocessing 
miRENDER_IMAGE_DELETE delete result images 
miRENDER_CHECK debugging: check scene 
miRENDER_DUMP debugging: dump to stdout 
miRENDER_ACCEL_DELETE delete BSP trees etc during postprocessing 
miRENDER_POSTPROC_FBC>* delete tessellation during postprocessing 
miRENDER_LIGHTMAP>* compute light maps 
miRENDER_REINHERIT?? redo parameter and material inheritance 
miRENDER_DEFAULT standard rendering and output shading 

miRENDER_PREPROC 


Preprocessing traverses the entire scene graph. It builds a leaf instance list, 
which contains one newly allocated instance for each geometric object in 
the scene, and all its flags and transformation matrices compounded and 
inherited from the instances in the scene graph. If an object or light is multiply 
instanced, it will have multiple instances in the leaf instance list. All geometry 
shaders that are found during traversal are called to produce scene elements 
to be added to the leaf instance list. Preprocessing is required whenever the 
scene geometry changed, either because object geometry changed or because 
instances or groups that place them into the 3D world changed. Preprocessing 
is not necessary if only shader parameters change. 


Preprocessing also tessellates all objects that have not been previously 
tessellated, and whose tessellation cannot be shared with another instance 
of the same object. The preprocessor manages caches and “dirty bits” to 
determine which objects need tessellation. 


Note that displacement mapping is not taken into account — if a displacement 
shaderis added, removed, or changed, directly or indirectly through 
inheritance or shader or phenomenon assignment, or if the displacement 
shader has other external dependencies, this does not cause retessellation. 
The application should use mi_scene_edit and mi_scene_edit_end on the object 
to force retessellation in this case. Note that preprocessing does not in any 
way change the scene graph (other than manipulating dirty flags), it only 
creates additional information. 
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miRENDER_OBJ_DELETE 


This bit forces deletion of the source geometry of all objects after tessellation. 
Source geometry includes polygons, free-form surfaces, and subdivision 
surtaces that require tessellation into triangles in order to be rendered. Since 
rendering does not need the source geometry, this flag allows deleting it to 
conserve memory. This is a sub-mode of preprocessing, and it has no effect 
if miRENDER_PREPROC is not set. 


miRENDER_SHADOWMAP 


miRENDER_DISPLAY 


If the scene contains shadow-mapped light sources, create the shadow maps. 
This involves scanline rendering the scene from the point of view of each 
light source. The scene must already have been preprocessed, either with the 
current or some previous call to mzi_rc_run. This mode requires rendering 
capability of the raylib. It is independent of miRENDER_RENDER. 


If set, rendered image rectangles are sent in realtime either to the file 
descriptor specifies by the zmgpzpe argument if nonzero, or to a socket opened 
by another program such as the imf_disp viewer that has connected through 
the 128-byte stub output file. The zmgpipe descriptor takes precedence over 
an external socket connection. This bit has no effect unless miRENDER_RENDER 
is also set. It cancels a previous call to mi_disp_relay init because raylib can 
only handle one display connection at a time. 


miRENDER_DISPLAY°? 


miRENDER_RENDER 


miRENDER_RENDER 


If set along with miRENDER_DISPLAY, indirect light computed by finalgather 
preprocessing is shown as if it were rendered rectangles. Display is very 
coarse because at that stage no refinement and filtering is done, but it gives 
an indication of preprocessing progress. It is not on by default because it 
slows down preprocessing and consumes extra memory for the pixels sent 
to the viewer. 


Render the scene. The scene must have been preprocessed either in this or 
some previous call to mi_rc_run. This bit is ignored if miRENDER_FB_RESTORE 
is also set because in this case the rendering result would be immediately 
overwritten from the saved frame buffers. 


Render the scene. The scene must have been preprocessed either in this or 
some previous call to mi_rc_run. This bit is ignored if miRENDER_FB_RESTORE 
is also set because in this case the rendering result would be immediately 
overwritten from the saved frame buffers. 


miRENDER_RENDER_FG>> 


Perform final gather preprocessing. For backwards compatibility reasons, 
this flag is implicitly turned on if the miRENDER_RENDER flag 1s set. It is still 
useful to perform final gather preprocessing without rendering. 


606 


miRENDER_FB_SAVE 
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Save all frame buffers between rendering and calling the output shaders. Since 
output shaders generally overwrite the frame buffers, this preserves a clean 
copy that later allows re-running the output shaders without re-rendering 
first. If there are already saved frame buffers, the old saved frame buffers 
are deleted first. The three frame buffer mode bits are designed to support 
fast output shader tuning. Note that pixel previewing using prevmask does 
not apply to output shading because output shaders, by definition, always 
operate on all pixels. 


miRENDER_FB_RESTORE 


Restore previously saved frame buffers. This bit is ignored if miRENDER_FB_ 
SAVE is also set because that would imply a redundant copy. 


miRENDER_FB_DELETE 


Delete previously saved frame buffers. This bit is ignored if miRENDER_FB_ 
SAVE is also set. This should be done before (or together with) postprocessing 
to free up the memory used by the saved frame buffers, which may be very 
large. 


miRENDER_OUTPUTSH 


Call the output shaders on the frame buffers created either by rendering or 
a frame buffer restore operation. This generally changes the frame buffers 
but leaves the saved frame buffers intact. Output shading includes writing 
to output files, unless explicitly disabled by the appropriate bits in the no_ 
output flag in the options. 


miRENDER_POSTPROC 


Postprocess the scene. This involves deleting the leaf instance list and all 
temporary objects created by geometry shaders. Note that output shaders 
should always be called between preprocessing and postprocessing, not 
outside this bracket, because they might access information such as the 
modified camera or object or light data that is no longer available after 
postprocessing. Note that preprocessing does not implicitly postprocess; it 
must always be done explicitly. There should always be one postprocessing 
step for every preprocessing step. 


miRENDER_IMAGE_DELETE 


Delete the result images. Normally, the result images are passed through 
output shaders and written to files as specified by the output list in the 
camera, and then deleted after postprocessing before mi_rc_run returns. If 
this flag is cleared, the images are not deleted and are accessible with mz_ 
rc_run_query after mi_rc_run returns. It is important to delete the images 
explicitly with a call to mz_rc_run with mode miRENDER_IMAGE_DELETE (and 
probably no other flags) before the next rendering operation because the 
undeleted images are leaked otherwise (that is, mi_rc_run and mi_rc_run- 
query will not delete them, and will no longer be able to find them because 
their internal image tag list is overwritten). Note that pixel preview mode 
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miRENDER_CHECK 


miRENDER_DUMP 
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also retains the frame buffers, and implicitly ignores the miRENDER_IMAGE_ 
DELETE mode if set. 


After preprocessing and before shadow mapping and rendering, traverse the 
scene and perform consistency checks. This mode is independent of all others 
and can be used at any time and without other mode bits set. It is intended 
for application debugging. 


After preprocessing and before shadow mapping and rendering, traverse the 
scene and print the scene graph in a human-readable compressed form that 
provides a quick overview over the scene graph hierarchy. The verbosity 
level should be at least 3 (see mi_set_verbosity and miERR_INFO). This mode is 
also independent of all others and can be used at any time and without other 
mode bits set. It is intended for application debugging. 


miRENDER_ACCEL_DELETE 


Rendering accumulates various data structures such as BSP trees that stau 
around after rendering completes, because they would have to be recomputed 
for the next frame otherwise. However, if it is known that there will not be 
another frame for a while, and the application needs room for other purposes, 
it can tell postprocessing to delete such data by setting this flag. It has an 
effect only if miRENDER_POSTPROC is also set. (This flag is available in mental 
ray 2.1.43.4 and 2.1.44.44 and later.) 


miRENDER_LIGHTMAP?~* 


If the scene contains lightmap shaders, this flag enables calling them. If the 
flag is not set, lightmap shaders are ignored. This is useful to render only the 
light maps in a first pass, and later render the scene in a second pass where 
the generated lightmap images are used but not recomputed. 


miRENDER_REINHERIT?? 


This mode may be used only between frame renders, with no intervening 
postprocessing and preprocessing. It reevaluates material and parameter 
inheritance as post/preprocessing would, but without the overhead and 
without obsoleting the BSP tree and other acceleration data. It is useful 
for rapid incremental rendering of a scene in situations where instance 
parameters and instance materials change, but not the scene topology or 
any other instance fields (especially transforms and flags). 


Here are several examples for making use of the mode bitmap: 


mi_rc_run(miRENDER_DEFAULT, ...); 


This is what the standalone mental ray executable uses. It preprocesses, renders, and postprocesses. 
raylib is then ready to repeat the process for the next frame. 
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mi_rc_run(miRENDER_PREPROC + 
miRENDER_OBJ_DELETE, ...); 


/* use the tessellated geometry */ 


mi_rc_run(miRENDER_POSTPROC, ...); 


This combination is useful to tessellate a scene (or, more commonly, a sub-graph of the scene) 
and then making use of the result of the tessellation for wireframe or hardware-shaded displays. 
Note that even though raylib does not render, it is still necessary to define a camera and its 
instance, and adding the instance to the root group passed to mi_rc_run, because view-dependent 
approximations during preprocessing need to know where the tessellated geometry is in 3D space 
with respect to the camera. 


mi_rc_run(miRENDER_PREPROC + 
miRENDER_OBJ_DELETE + 
miRENDER_SHADOWMAP + 
miRENDER_LIGHTMAP, ...); /* mental ray 3.x only */ 


mi_rc_run(miRENDER_DISPLAY + 
miRENDER_RENDER + 
miRENDER_OUTPUTSH + 
miRENDER_IMAGE_DELETE, ...); 


/* more mi_rc_run calls */ 


mi_rc_run(miRENDER_POSTPROC, ...); 


Here, the scene is preprocessed once, and then rendered one or more times, and then 
postprocessed. Rendering multiple times inside the preprocess/postprocess bracket is useful 
for shader parameter tuning. The middle call to mi_par_run may be repeated every time the user 
has changed a shader parameter, for example to tune a material color. This works very well with 
shader previewing, which lets mental ray re-render only those pixels that might be affected by 
the change. Note that this example cannot deal with scene graph changes — it keeps rendering 
the leaf instance list created by the first call to mi_par_run and assumes that it is still valid, and no 
objects have been changed, added, or deleted. 


mi_rc_run(miRENDER_PREPROC 
miRENDER_OBJ_DELETE 
miRENDER_SHADOWMAP 
miRENDER_LIGHTMAP 
miRENDER_RENDER 
miRENDER_FB_SAVE 
miRENDER_OUTPUTSH 
miRENDER_IMAGE_DELETE, ...); 


/* mental ray 3.x only */ 


++ +++ + + 


mi_rc_run(miRENDER_FB_RESTORE + 
miRENDER_OUTPUTSH, ...); 
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/* more mi_rc_run calls */ 


mi_rc_run(miRENDER_FB_DELETE + 
miRENDER_POSTPROC, ...); 


This example is similar to the previous except that only the output shaders and not the entire 
rendering operation are tuned. If the user wants to tune parameters of the output shaders attached 
to the camera, it would be inefficient to re-render every time to recreate the images that the output 
shaders operate on. Instead, the scene is rendered only once and then saved to the save frame 
buffers before calling the output shaders for the first time. After that, the save frame buffers are 
simply restored before calling the output shaders again. Finally, when tuning has finished, the 
save frame buffers are deleted and the scene is postprocessed. 


Obviously, all these fragments are incomplete — the return code is not checked, and there are no 
calls to mi_par_aborted between the various calls to mi_par_run that could stop the render loop if 
the user has pressed a Cancel or Abort button. Also, before mi_par_run can be called for the first 
time, a scene must have been constructed using mi_api_* calls. 


The following pseudocode describes the operation of mi_rc_run: 


if (miRENDER_PREPROC) 
preprocess; 


if (miRENDER_DUMP) 
scene_dump(root_group) ; 


if (miRENDER_CHECK) { 
scene_check(option_tag) ; 
scene_check(root_group) ; 


if (miRENDER_SHADOWMAP && options->use_shadow_maps) { 
mi_img_invalidate_local_images ; 
build_shadow_maps ; 


if (options->no_images > 0) { 

if (no frame buffers || !options->pixel_preview) { 
create_frame_buffers; 
mi_img_invalidate_local_images ; 

Z 

if (miRENDER_DISPLAY) 
if (imgpipe) init_display_pipe; 
else init_display_socket ; 


if (miRENDER_LIGHTMAP) /* mental ray 3.x only */ 
build_light_maps; 


if (miRENDER_RENDER) { 
build_photon_maps ; 
render; 
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ty 
if (miRENDER_FB_SAVE) 
copy frame_buffers to saved_frame_buffers; 


if (miRENDER_FB_RESTORE && !miRENDER_FB_SAVE) 
copy saved_frame_buffers to frame_buffers; 


if (miRENDER_FB_DELETE && !miRENDER_FB_SAVE) 
delete saved_frame_buffers; 


if (miRENDER_OUTPUTSH) 
call_output_shaders; 


mi_img_invalidate_local_images; 
if (!options->pixel_preview && !miRENDER_IMAGE_DELETE) 
delete_frame_buffers; 
} 
if (miRENDER_POSTPROC) { 
scene_postprocess; 
if (miRENDER_ACCEL_DELETE) 
delete bsp_tree_etc; 


RC Query Function 


enum miRc_query { 
miRCQ_NO_LIGHTS, 
miRCQ_NO_LEAF_INSTS, 
miRCQ_LIGHTS, 
miRCQ_LEAF_INSTS, 
miRCQ_CAMERAS , 
miRCQ_IMAGE 

}; 


miBoolean mi_rc_run_query ( 
enum miRc_query mode, 
int arg, 
void *result) ; 


This function picks up information from a previous mi_rc_run call. It is useful when that function 
is called with fewer mode flags than miRENDER DEFAULT to split the rendering operation, especially 
between preprocessing and postprocessing, and between rendering and deleting the result images. 


mi_rc_run_query accepts a mode that determines what to query, an argument that further describes 
which element to return, depending on the mode, and a result pointer that must point to a variable 
that the queried data is stored in: 
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*vesult type | returned data 


miRCQ_NO_LIGHTS number of light leaf instances 
miRCQ_NO_LEAF_INSTS number of object leaf instances 
miRCQ_-LIGHTS light leaf instances 


miRCQ_LEAF_INSTS object leaf instances 
miRCQ_CAMERAS camera leaf instances 
miRCQ_IMAGE me rendered image 


The first five may be queried after calling mz_rc_run with the flag miRENDER-PREPROC. They 
remain valid until calling again with this flag, regardless of other flags. 


The last mode 1s valid after calling miz_rc_run to render an image, without the miRENDER_IMAGE_ 
DELETE flag (which is on by default). Image frame buffers can then be queried with arg set to one 
of the miRC_IMAGE_* frame buffer numbers. If a frame buffer is not defined, a null tag is returned. 
It is necessary to call mi_rc_run with miRENDER_IMAGE_DELETE before rendering the next frame 
to prevent the images from being leaked. 


This function returns miFALSE if an illegal mode or an arg out of range is passed, and miTRUE 
otherwise. 


Here is an example: 


int arg; 
miTag tag; 


mi_rc_run(miRENDER_DEFAULT & ~miRENDER_IMAGE_DELETE, ...); 


for (arg=0; arg < miRC_MAX_IMAGES; arg++) { 
mi_rc_run_gquery(miRCQ_IMAGE, arg, &tag); 
if (tag) 
/* write tag to an image file */ 
} 
mi_rc_run(miRENDER_IMAGE_DELETE, ...); 


Note that in principle, this function returns valid values during rendering, and can be called from 
abort or display callbacks. However, shadow mapping and other phases do not necessarily use the 
same camera, options, and images returned by mi_rc_run_query. Also note that while rendering 
ona network of hosts, the images are incomplete and contain only tiles rendered locally (possibly 
none at all, in relay configurations). 


miBoolean mi_phen_requirement_mgmt ( 
miBoolean enable) 


Enable or disable requirement management in mental ray. The default is enabled. If disabled, the 
mi_phen_*_requirements calls have no effect; if applicable the miPhen_-requirement structure 1s 
all zero. This can be used by applications (Softimage Sumatra) that handle all the flags and shaders 
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before starting to render. Note that this function will not be available in the next generation of 
mental ray. 


RC Traversal Callback Function>* 


typedef miBoolean (*miTraversal_func) ( 


void *xdata, /* opaque this pointer */ 

struct miInstance *parent, /* previously inherited instance */ 
struct miInstance *inst, /* new instance to be inherited */ 
miTag *path, /* path: root group .. curr inst */ 
int pathlen) ; /* number of tags in path[] */ 


void mi_rc_run_traversal_cb( 
miTraversal_func cb, /* traversal function to call */ 
void xdata) /* this passed to traversal func */ 


This function sets the traversal function used during traversal of the scene graph. It will be called 
once for each instance in the graph. The function may change the current instance imst based on 
the inherited information. If it returns false, the traversal of this branch of the scene DAG 1s 
terminated. A traversal function set with mi_rc_run_traversal_cb overrides the traversal function 
set in the options block (if options — inh_is_traversal>:' is true). 


mental ray 3.1 allows setting the traversal function in the options, calling the izh_func tag passed 
to mi_rc_run if the inh_1s_traversal flag is set in the options block. This makes the mi_rc_run_ 
traversal_cb call largely obsolete. 


5-3-2 Realtime Image Display (DISP) 


Concurrent image display means that rendered RGBA data is made available while it is being 
rendered, ona tile-by-tile basis. RGBA tiles are sent to one of four destinations listed below. Note 
that the API has changed significantly in mental ray 3.1, which is not compatible with mental ray 
2.1 or 3.x. The underlying concepts are similar, but the API was changed for two reasons: any 
number of concurrent streams is supported, and the tiles are handled by a separate thread that 
will maintain a fast response rate regardless of system load, instead of exhibiting the long delays 
between tiles that sometimes occurred with earlier versions. 


1. Toa file descriptor, which must be passed to mi_rc_run function as its second argument. This 
mode is enabled either by calling mi_disp_stream_pipe_begin’'', or by passing a nonzero file 
descriptor and setting the miRENDER_DISPLAY flag (which is part of the default flag mask) to 


mi_rc_run, which then calls mi_disp_stream_pipe_begin>"'. 


2. To a callback function, which is installed with the mi_disp_relay_init*', mi_disp_stream- 
start?*, or mi_disp_stream_cb_begin>' functions. In mental ray 2.1 or 3.z, this works only if 
there is no file descriptor (method 1). mental ray 3.1 does not have this limitation. 
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3. ToaJPEG stream’. This also involves a callback function, but instead of pixel rectangles, 
raw blocks of compressed JPEG are passed to the callback. In this mode, mental ray switches 
to a top-down rendering order. JPEG streams are created with the mi_disp_stream_jpeg_cb_ 
begin?! function. 


4. Toasocket whose number is written to files. If there are file output statements in the camera, 
the specified image files are written as 128-byte files containing an ascii line such as 


ray3.4,720,576, voxel, 2478,1.000000 , 140528 


The comma-separated fields contain the mental ray version (2.0 for both mental ray 2.0 and 
mental ray 2.1, and 3.3 for both mental ray 3.3 and 3.4 since the display format is compatible), 
the width and the height of the image, the name of the master host (here, “voxel”), a socket 
ID, the gamma value, and the process ID of the master mental ray. A newline and a null byte 
follow. The remainder of the file is undefined. Programs such as imf_disp can connect to the 
given socket on the given host to obtain RGBA tiles. This mode works only if there is no 
file descriptor (method 1) or callback (method 2). The 128-byte file is overwritten with the 
final image when rendering completes and the output statements in the camera are executed. 


The 128-byte file contains -1 as port numbers in mental ray 3.3.3 or higher if firewall 
mode was enabled by the package that mental ray is integrated in. This mode attempts to 
circumvent defective Windows “firewalls” that consider any attempt to create a socket an 
Internet access, and block it. mental ray tries to limp along in such a case by avoiding all 
socket creates. This is a Windows-specific problem, Linux and Unix are fine. 


mental ray 3.1 and later offer the mi_disp_stream_socket_begin>' function, which installs a 
user-defined socket and starts sending data to that socket. This socket is independent of 
the socket created automatically by mental ray for file output statements, and will not get 
written to any files. The difference between a file descriptor (method 1) and a socket is that 
the former begin the transfer with a type-5 message and the latter with a type-6 message (see 


below). 


The protocol used to send data to a file descriptor or to a socket are identical. Data is sent in 
packets. Each packet consists of a header, followed by optional image data. The header consists of 
five integers in network byte order (big-endian, high byte first): one packet type code followed 
by four parameters. The following packets are defined: 


Cd er a 6 ne 


frame 0 start of a new frame 
width height gamma image size (file descriptor only) 
xl xh yl yh | 4-(yh—yl+1) | new RGBA image tile 


- (xh — xl +1) 
end of image 
refuse connection 


Image size packets (type 5) are sent only to file descriptors and not to sockets because socket 
readers have obtained that information from the 128-byte file already. The gamma value is a 


614 5 Integration of mental ray 


floating-point value, not an integer. mental ray 2.1 and 3.0, but not 3.1 and later, refuse connections 
(type 3) if there is already another connection; this can happen only during socket connection 
attempts. Packets with types not listed in the table above should be quietly ignored, they will 
consist of only the header. 


Only image data packets (type 2) have data after the header. Data is sent in RGBARGBA... 
order, with eight bits per pixel component, beginning with the lower left corner of each tile. The 
coordinates of the lower left tile pixel (x/, y/) and of the upper right tile pixel (x/, yh) are in 
absolute image coordinates. If output shaders run, the image may be sent multiple times, once 
as rectangular tiles during rendering and then once per output shader in blocks of scanlines. The 
order of tile and scanline packets is undefined. 


Image data callbacks must be installed and uninstalled with the following two functions. Unlike 
the file descriptor and socket methods, the calling application is aware of when frames begin and 
end, and has access to the result of output shaders, because it calls mz_rc_run and has access to all 
data before and after mi_rc_run. Therefore, only image tile data is transferred during rendering, 
but not after output shading. Also, there are no notifications when frames begin and end, and 
what the resolution and gamma values are (all this is already known by the caller of mi_rc_run). 
The callback is intended only for showing rendering progress in the application’s GUI. 


5.3.2.1. mental ray 2.1 and 3.0 


typedef void (*miRelay_display_func) ( 


int x1, 

int yh. 

int width, 
int height, 
milmg_image *image, 
int xoLt,, 
int yoff) ; 


miBoolean mi_disp_relay_init ( 
miRelay_display_func cb) 


*-! This function installs a callback function cb. If another callback function was installed (either 
by another call or by file descriptor or socket transfers, which are basically special-purpose 
callbacks hardcoded in raylib, see above), it is replace with the new callback. The callback has the 
following arguments: 


xl The X position of the left edge of the image data tile. 
yl The Y position of the bottom edge of the image data tile. 
width The width of the image data tile. 


height The height of the image data tile. 
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image A frame buffer that contains the image data tile. This may either be a full 
frame or a temporary tile-sized frame buffer. 


xoff The X offset into the zmage where the tile image data is found. If wage is a 
full frame buffer, xoff has the same value as x/; if it is a tile-sized image buffer, 
it has the value 0. 

yoff The Y offset into the zmage where the tile image data is found. If image is a 
full frame buffer, yoff has the same value as y/; if it is a tile-sized image buffer, 


it has the value 0. 


mi_disp_relay_exit returns miTRUE on success and miFALSE on failure. (At this time it always 
returns miTRUE.) 


void mi_disp_relay_exit (void) 
2-1 This function uninstalls a callback function. Socket connections are then possible again. 


void mi_disp_stream_start ( 


void (*rcb) (void *, miTag, int, int, int, int), 
void (*jcb) (void *, void *, int), 

void *arg, 

int quality) 


°-* This function replaces the relay initialization function above. It installs a callback rcb that 
receives raw tile info, and a JPEG callback jcb that receives blocks of a JPEG stream. Either 
function may be a null pointer. The argument arg is passed to both callbacks; it is intended to 
pass context, such as a C++ this pointer. The quality argument is a number in the range 1 (low) 
to 100 (high) that determines the JPEG compression quality for the JPEG callback jcb. 


The raw callback receives the arg pointer, the tag to an image of type milmg_image (use mi_db_ 
access and mi_db_unpin), and the four corners of the image in the full frame buffer. The corners 
are specified as Xiows Vows Xhighs and ypigh- The coordinate origin is the lower left corner. The 
image rectangle has the width xpio, — XJow + 1 and the height ypich — Yow + 1. 


The JPEG callback receives the arg pointer, a pointer to a byte buffer, and the number of valid 
bytes in the buffer. The concatenation of all buffers forms a JFIF image file. When the stream 
is complete and all buffers have been sent, one more call with a buffer pointer 0 and a size 0 1s 
performed. Note that if jcb is nonzero, mental ray switches the rendering tile order to top-down. 


There is no corresponding stop function. To disable streaming, call mi_disp_stream_start with two 
null callback pointers. 
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5.3.2.2. mental ray 3.1and Higher 


mental ray 3.1 uses the notion of a stream for all realtime image display methods. For each 
method, there is a begin function that creates the stream, and the is a single end function that 
destroys a stream. Streams are identified by an identifier of type miStream. While a stream is 
open, it propagates frame begin/end and tile begin/end information, in a format that depends on 
the stream method. 


Note that mental ray 3.1 runs the DISP module in a separate thread. This means that display 
callbacks are not called in the thread that set up the callback stream. Also, there may be a small 
delay before a terminated stream stops sending rectangles; this needs careful attention if streams 
are created and terminated in the middle of rendering. 


miStream mi_disp_stream_pipe_begin( 
int fd) 


°-! Create a pipe stream that sends messages of type 5 when a frame begins, 4 when a frame ends, 
and 2 for every finished rectangle. The message format can be found in the table on page 613. 
Messages are written to the file descriptor fd. The returned miStream code identifies the stream 
and must be used for terminating the stream using mi_disp_stream_end. The stream will remain 
open until it is explicitly terminated. 


miStream mi_disp_stream_socket_begin( 
int fd) 


*-' Create a socket stream that sends messages of type 6 when a frame begins, 4 when a frame ends, 
and 2 for every finished rectangle. The message format can be found in the table on page 613. 
Except for the type of the frame begin message, the stream is similar to a pipe stream. 


typedef void (*miDisp_cb) ( 


void *arg, 
mitag *image, 
int oe 

int Ts 

int xh, 

int yh) ; 


miStream mi_disp_stream_cb_begin( 
void *arg, 
miDisp_cb rcb) 


°-! Create a callback stream. The callback will be called in four situations: when the frame begins 
(mage, xl, and yl will be 0 and xh and yh contain the image resolution from the camera); when 
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the frame ends (all arguments except arg are 0); when a rectangle begins (image is 0 and xl, yl, xh, 
and yh describe the position of the lower left and upper right corner of the rectangle in image 
pixel coordinates); and when the rectangle is finished (same except image contains valid image 
rectangle tags). The distinction between rectangle begin and end is available only for callback 
streams (although later versions may make it available for sockets and pipes as well). It allows 
previewers to announce that a rectangle has started rendering using little cross-hair markers or 
similar, to give the user better feedback. For all calls, the arg argument is an opaque pointer that 
always has the value given to mi_disp_stream_cb_begin; it can be used to pass a this pointer to a 
C++ method. 


Note 1: mental ray 3.1 sends an image that corresponds exactly to the specified size, such that the 
bottom left pixel is always found at coordinate (0, 0) regardless of x/ and yl. This was changed in 
mental ray 3.2, which always provides the complete frame buffer tag, so that the lower left pixel 
of the current rectangle is found at (x/, y/). If the callback code is not changed accordingly, the 
resulting image will contain many black or misplaced pixel rectangles. 


Note 2: in mental ray 3.3, mage is a miTag pointer, not a tag as in earlier versions. This allows 
access to all frame buffers, not just the main color frame buffer. The pointer is either zero (see 
above), or points to an array of tags. To obtain the same tag that mental ray 3.2 would have 
passed, use image [miRC_IMAGE_RGBA], which is guaranteed to be non-null. The other miRC_ 
IMAGE_* indices are all available as well but may be null tags if the corresponding frame buffer is 
unavailable. Also, the tags pointed to are the full frame buffers, not the small image rectangles, so 
it is necessary to use the x/ and y/ arguments to offset into them. 


Note 3: in mental ray 3.4, image is an opaque miRc_mapfb pointer, not a miTag pointer. The 
pointer is either zero (see above) or points to a structure in memory. To access a frame buffer 
image, use mi_disp_fbmap and m1_disp_fbunmap. These functions expect the miRc_mapfb pointer 
in addition to the frame buffer index, which is one of the miRC_IMAGE_* indices. This change was 
necessary because mental ray 3.4 does not maintain frame buffers in memory at all. 


typedef void (*miDisp_jpeg_cb) ( 


void *arg, 
void *data, 
int size); 


miStream mi_disp_stream_jpeg_cb_begin( 


void *arg, 
miDisp_jpeg_cb jcb, 
int q) 


>-! Create a JPEG callback stream. The callback will be called in two situations: when the frame 
ends (data and size are 0), and when enough rectangles have been rendered and compressed to 
send more JPEG data (data points to a buffer containing size bytes). Due to the nature of JPEG 
compression, there is no direct association between pixel rectangles and buffers. If all data passed 
by the callback is written to a file in sequence, a complete JFIF image results. The arg pointer is 
again an opaque user-defined pointer. 
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As a side effect, mi_disp_stream_jpeg_cb_begin sets the tile order to top-down to optimize 
streaming. It can be restored to another order with mi_rc_set_taskorder. 


JPEG streaming is not currently available in mental ray 3.1. 


miStream mi_disp_stream_jpeg_cb_begin( 
miStream vstr) 


>! Terminate a stream. vstr is the stream identifier returned by the function that created the 
stream. No more data will be sent down this stream. However, since the DISP module runs in a 
separate thread, there may be calls still scheduled or in progress. 


5-3-3 Extended API 


The functions described in this section are extensions to the geometry shader API described in 
“Programming mental ray” [PROG]. Functions that begin with mz_api are used to create a scene 
in the database. This is a high-level API that is also used by mental ray’s own scene translator 
and geometry shaders. It is largely based on named database elements. The later SCENE and DB 


chapters will provide a more low-level access to the underlying scene storage mechanisms. 
5.3.3.1 Messages 


void mi_api_error ( 
char NSE <4) 


This API function is called by API whenever an error occurs. It is part of the call interface to allow 
the API caller to print its own messages in a format similar to that of API itself. The arguments 
work in the same way as those of mi_error. 


void mi_api_warning ( 
char amSg, ...) 


This is the corresponding warning message function called by API. 


5.3.3.2. Notification Callbacks 


miBoolean mi_api_notify_callback( 


void (*cb) (char *name , 
miTag tag, 
miTag phen_tag, 


char mode) ) 


5.3. Call Interface 619 


Install a notification callback function. Whenever API creates, recreates, or deletes a toplevel tag, 
the specified callback cb is called with the element name, the element tag, and a mode character 
that is ’c’ for creation, ’i’ for an incremental change, or ’d’ for deletion. Toplevel tags are 
elements with persistent names such as objects, cameras, declarations, shaders etc. that have a 
name and a tag, but not bases or surfaces (which are not at the top level but encapsulated in 
objects, so their names are lost when the object definition is finished). If the element is created 
or modified in phenomenon scope, the tag of the enclosing phenomenon is passed as phen-_tag; 
otherwise phen_tag is a null tag. 


More precisely, the callback is called for options, cameras, file output statements, instances, 
instance groups, lights, objects, materials, image textures, function declarations, phenomenon 
declarations, and named (but not anonymous) shaders. 


The name may be a null pointer, and should be mimem_strdup’d if stored because it may be 
released or destroyed after the callback returns. Since API often creates hidden unnamed elements 
such as instances and instance groups for objects containing multiple object groups, sometimes 
no name is available. The callback is called when the element is created, not when API has finished 
filling it with parameters. 


The main purpose of this callback is to let a caller who has read a sub-scene (probably after 
entering a scope, see below) delete it at a later time. To delete a scene element that caused a call 
to the notify callback, call mi_api_delete(name) if a nonzero name was passed, or call mi_scene_ 
delete_one(tag) if the name was a null pointer. mz1_api_delete calls mi_scene_delete_one and also 
removes the name from API’s symbol tables. These delete functions will take care of unnamed 
sub-tags that did not cause calls to the notification callback. Do not call mi_scene_delete because 
that would also delete named subtags which did cause calls to the callback, which might then be 
deleted twice. Note that calls to mi_api_delete cause a call to the callback with mode ’d’. 


miBoolean mi_api_error_callback( 
void (*xerr_cb) (char *, int), 
void (*warn_cb) (char *, int)) 


Install error and warning callbacks. Two functions must be passed that accept a string argument 
(the message) and an integer (the message code). Message codes are unique identifiers in the range 
1..999 that are integrated into the raylib error message codes as the last three digits. 


The API module will call the callback functions whenever an error or a warning occurs, with an 
appropriate message. The function may print the message to the terminal or elsewhere, together 
with useful context information such as the current file name and line number if available. If no 
callbacks are installed, they default to mi_nerror and minwarning, respectively, with a second 
argument of "%s" to prevent evaluation of percent characters. Note that all API functions also 
return miFALSE or a null pointer or a similar failure indicator if the requested operation could 
not be performed, in addition to any warning or error messages. 
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5.3.3.3. Function Parameter Access 


These functions allow access to shader parameters. They can be used to incrementally change 
parameter values without redefining the entire shader parameter block every time a GUI slider 
is moved. Note that it is still necessary to access the shader miFunction with mi_scene_edit and 
mi_scene_edit_end if a new parameter value is written to inform raylib that a change was made. 


typedef struct { /* info about p type : */ 
miParam_type type; /* expected value type */ 
int size; /* size in bytes of one */ 
int nval; /* max # of values */ 
char code; /* code char for decl */ 
char kname ; /* type name string */ 


} miApi_typeinfo; 


miApi_typeinfo *mi_api_get_typeinfo( 
miParam_type type) ; 


The miApi_typeinfo structure may change in future versions. It is used to inform other modules 
that access function and declaration parameters about parameter types without keeping the same 
information in many different places. 


miBoolean mi_api_parameter_lookup( 


miParam_type type, /* type of <name> */ 


miBoolean *is_array, /* true for arrays */ 
int *xoffs, /* offset in param blk */ 
miTag decl_tag, /* decl to look up in */ 
miBoolean out, /* output or input? */ 
char *name ) /* name to look up */ 


Given a parameter name, return the offset into the parameter struct where the value is stored. 
The parameter name may contain dots but no array subscripts because the array member layout 
is not known until we actually get values and know how many members exist. This function can 
parse both the output struct and the input parameters. It returns the parameter type type, a flag 
is_array if it is an array, and an offset offs into the parameter block where the value is stored, or 
return miFALSE on failure. 


miBoolean mi_api_parameter_path_lookup( 


miTag *xtag, /* tag of miFunction */ 
int *offs, /* func->param offset */ 
int *size, /* size of value */ 

miParam_type *ptype, /* type of parameter */ 
char *path) /* gui->control names */ 
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Given a dot-separated shader parameter path, return the tag of the referenced miFunction, the 
offset offs into that function’s parameter block, the size of the value referenced there, and the 
type ptype of the parameter. The path begins with the shader instance name, followed by a dot, 
followed by the parameter name. If the parameter name has substructures, the names are again 
dot-separated. Return miFALSE on failure. 


miBoolean mi_api_parameter_offset_lookup ( 


miParam_type *ktype, /* type of <name> */ 
miBoolean *is_array, /* flag, true for arrays */ 
char kkname , /* parameter name */ 

int *code_idx, /* code string index */ 
miTag decl_tag, /* decl to look up in */ 
miBoolean out, /* output or input? */ 

chins offs) /* offset in param blk */ 


Given a parameter offset, return the name of the parameter at that offset. This is the reverse 
Operation to mi_api_parameter_lookup. The returned parameter name may contain dots. If the 
offset does not point to the beginning of a parameter, the result is undefined. As a special case, 
asking for the unnamed shader output at offset 0 always succeeds without name matching. 


5.3.3.4 User Interface Definitions 


Graphical user interfaces (GUIs) are accepted by the MI parser and the API module. API passes 
all information on to the PHCR module, which provides the actual user interface for editing 
shader parameters. PHCR is not included in raylib, it is available only in separate executables. 


All GUI functions are no-ops if PHCR is not linked in. 


miBoolean mi_api_gui_begin( 
char *name ) /* gui name */ 


Begin the definition of a new user interface named name. The name will generally be the name 
of the declaration or function that the GUI describes. If there is already a user interface with the 
given name, it is deleted. If two different concurrent threads operate on a GUI with a given name, 
the changes by both are compounded; concurrent creation should be avoided. 


miBoolean mi_api_gui_end(void) 


Complete the definition of the GUI. The previous and this function bracket the user interface 
definition. All other GUI functions except mi_api_gui_default can only be used between begin 
and end. 
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miBoolean mi_api_gui_control_begin( 
char *name , /* control name */ 
char *ktype) /* control type */ 


After beginning the GUI, controls such as buttons, sliders, color choosers and others, can be 
added to it. The control is named name, which may be a null pointer for unnamed controls. GUIs 
that describe a shader should have controls named after input shader parameters; PHCR will 
connect these controls to the shader directly. The possible control types type are defined by the 
PHCR module. 


miBoolean mi_api_gui_control_end (void) 


After beginning a control, attributes and sub-controls may be defined. After the last definition, 
the control must be completed with this call. After completion, another control may be begun, 


or the GUI can be ended. 


miBoolean mi_api_gui_push(void) 


Some types of controls, such as cell containers or menus, can contain sub-controls. Between 
control begin and end, the nesting level can be pushed to begin the subdefinition, which contains 
its own control begin and end pairs and ends with a pop operation. Cell containers can contain 
multiple subdefinitions, each with its own push/pop pair; all others may contain only one. In the 
cell container pair, each push/pop pair fills the next cell (in row-major order beginning at 0/0); 
but the cell can also be set explicitly with mi_api_guiattr("cell", ...) before the push. 


miBoolean mi_api_gui_pop (void) 


Complete the definition of a subdefinition. 


miBoolean mi_api_gui_attr( 


char *xname, /* parameter name */ 
miParam_type type, /* bool, scal, string */ 
int nval, ...) /* # of values, vals */ 


Apply an attribute to the current GUI or control. Attributes control the appearance; there are 
attributes for foreground and background colors, size, value, limits, number of cells and cell 
number, etc. For a complete list see the PHCR module documentation. Attributes always apply 
to the GUI or control most recently begun at the current push/pop nesting level. Attributes may 
not be set between a push and a control begin. 
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miBoolean mi_api_gui_default ( 


miTag tag, /* decl or function */ 
char *xname , /* name of <tag> */ 
miBoolean override) /* recreate? */ 


The previous GUI calls are used for defining a GUI explicitly. This call is independent and creates 
a GUI automatically given the tag of a function declaration or function (the result is the same 
in both cases except that parameter values are applied in the function case). The tag specifies the 
declaration or function to be used as a template, name is the GUI name to create (it should agree 
with the shading function name if tag is a declaration), and override controls whether the default 
GUI should replace an existing GUI definition. It is normally miFALSE because default GUIs 
should not override explicitly defined GUIs. 


5.3-3-5 Tessellation and Rendering 


Tessellation is the operation that turns the defined scene into a renderable representation 
containing triangles, ready for rendering. The actual render process that creates images or other 
representations of the triangles is outside the scope of API. The caller of API is free to let every 
type of renderer use the data created here: ray tracers, scene viewers, wireframe viewers, etc. 


miBoolean mi_api_render ( 


char *group_name, /* root group */ 
char *Cc_inst_name, /* camera */ 

char *xoption_name, /* options */ 

char *inh_name) /* inher function */ 


After the scene has been set up, it can be prepared for rendering. This can be done implicitly 
using frame calls (see above), but the recommended method uses direct render calls. The name of 
the root instgroup, the name of the camera instance to use (which must also be added to the root 
group explicitly), the options element name, and an optional inheritance or traversal*"' function 
name must be given. The inheritance/traversal function is not a shader, has no custom parameters 
and is not declared. It is sufficient if it exists under the given name in one of the libraries linked 
with the LINK module. mi_api_render does not start rendering itself but only does some checks, 
prepares API for rendering and returns to the caller. 


miBoolean mi_api_render_params ( 


miTag *root_group, 

miTag *camera_inst, 
miTag *camera, 

miTag *options, 
miInh_func *inheritance_func) 


Give access to the render parameters. This function can be called after a successful mi_api- 
render. The function using these parameters typically calls mi_rc_run next. The inh_is_traversal?"' 
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field in the options determines whether inheritance_func is an inheritance function or a traversal 
function>". 


miBoolean mi_api_render_release (void) 


After rendering has completed, this function must be called to clean up initializations performed 
by mi_api_render_params. Tessellation and Rendering is normally bracketed by mi_api_render- 
params and mi_api_render-_release. Despite its name mi-_api_render is not itself involved in 
rendering in any way, it just records the names of the root group, camera, camera instance, 
and options; basically it implements the render statement in the .mi language. The reason for 
this split is to return control to the calling application when a render statement is encountered. 
The application may want to draw a wireframe on the display, echo to a file, translate to another 
format, but not actually render anything. 


5.3.3.6 Registry 


The registry is a sequence of named entries, each of which contains an ordered list of key/value 
pairs. The entry name and all keys and values are strings. See the user manual for a description 
of the registry. The registry is a raylib database that is not related to other registries found on 
Unix and Windows NT, unless raylib is built into an application that provides a connection. In 
this case, the eval and lookup functions can access the system registry through this connection, 
but all begin/add/end definitions stay local to raylib and do not write to the system registry. No 
such connection is built into standalone versions of mental ray. 


miBoolean mi_api_registry_begin( 
char *regname ) 


Begin the definition of a new registry entry with the given name. The name must begin with { 
and end with }. It can later be looked up with mz_api_registry_eval and mi api registry _lookup. It 
the registry entry already existed, it is deleted along with all its key/value pairs and a new entry 
of the same name is created. 


miBoolean mi_api_registry_add( 
char *key, 
char *value) 


After beginning a registry entry with the previous function, key/value pairs can be associated 
with the registry entry using this function. The key and value arguments are unrestricted, but the 
eval and lookup functions assign special meaning to certain keys. 
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miBoolean mi_api_registry_end (void) 


Completes the definition of a registry entry begun with mi_api_registry_begin. Calls to mi_api-_ 
registry_add are allowed only between begin and end, and no eval. The eval and lookup functions 
may be used between begin and end, and they will see partially built registry entries. 


const char *mi_api_registry_eval ( 
char *regname ) 


Scan the string regname for substrings enclosed in curly braces {}. If the substring begins with a 
dollar sign, an environment lookup is performed using getenv; otherwise the registry is searched 
for the given name and, if found, the value associated with its value key is substituted. All 
characters not encodes in curly braces are passed through unchanged. If a registry lookup is 
successful, all its known keys are evaluated: 


The substituted string. 
The name of a shared library or object (typically a shader library) to load. 
The name of a source code file to compile and load. 


mi The name of a .mi scene file (typically containing shader declarations) to read and 
parse. 

echo A string to echo on the console, if the verbosity allows it. 

system | A shell command to execute. 


If the value of any key found in this way contains curly braces, it is evaluated in the same manner 
recursively. The final substituted regname string is returned as allocated memory that must be 
released with mi_mem_release by the caller. This function implements the .mi $lookup command. 


const char *mi_api_registry_lookup ( 
char *regname ) 


This function is equivalent to mi_api_registry_eval, except that only the value associated with the 
value key is returned, and no other keys are evaluated. 


5.3.3.7 Miscellaneous 


miBoolean mi_api_version_check( 
char *version, 
int mode ) 


Verify that the version string version is acceptable. The version string is a dotted sequence of either 
up to four numbers, such as 2.1.32.5. If less than four numbers are specified, the remainder is 


626 5 Integration of mental ray 


assumed to be zero. If mode is 0, raylib’s version must be version or greater; if mode is 1, raylib’s 
version must be version or less. This can be used to ensure that a scene matches the renderer, for 
example to specify that at least raylib 2.1 is required because the scene uses a 2.1 feature such as 
global illumination. 


5.3.4 Scene Module (SCENE) 


5.3.4.1 Introduction 


The Scene module provides a layer on top of the DB module. Its main purpose is to manage 
storage of the scene in memory, and to provide functions for global operations on the scene. 
It is used by all modules that deal with scene data, specifically for the API module. Scene also 
provides functions to convert the stored scene to a renderable representation that is accepted by 
other modules such as renderers, walkthrough viewers, or wireframe display functions, and uses 
the GAP module (the tessellator) for this purpose. In a dataflow sense, the Scene module sits in 
the pipeline between the translators and the renderer/viewer. 


From Scene’s point of view, a wireframe or hardware-shaded viewer is just another kind of 
renderer; the term “renderer” is used synonymously with “viewer” throughout the Scene 
documentation. The Scene module accommodates a wide range of different renderers; the render 
options data type provides fields sufficient for sophisticated ray tracers as well as simple hardware 
shading renderers. The Scene modules makes no assumptions about rendering-related data other 
than providing reasonable defaults; the actual interpretation of the data, and which parts of the 
data are used, depends on the renderer. 
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GAP 


Tesselation 


Translator/API Renderer/Viewer 


Storage 


Scene geometry data flow 


The bidirectional arrow from the translator to the DB module represents creating, editing, and 
deleting operations on the scene database. Some translators such as the .mi translator use the 
high-level API module to simplify scene creation. The Scene module manages this flow of data to 
keep track of changes. All other arrows represent the preprocessing stage managed by Scene that 
converts the source geometry created by the translator to a renderable representation accepted 
by the renderer. Note that the renderer may also access non-geometry data such as materials 
directly in DB without involving the Scene module; this diagram only shows geometry dataflow. 
There is also a postprocessing stage for cleanup after rendering completes. 


Specifically, the Scene module has three main functions: 


e Group 1 
High-level database element allocation. Unlike DB, database elements are allocated by 
type, and Scene provides defaults for each parameter. A unified set of operations is defined 
for each element type. Only Scene may use the allocation functions of DB directly; this 
ensures backwards-compatible changes to database data types and complete control over 
byte order conversions on the network. 


e Group 2 
Management of the scene DAG. All database elements that form the scene in the database 
are linked using tag references (a tag is a network-transparent ID number similar to a pointer 
maintained by DB). The Scene module provides functions to build and modify the DAG, 


628 5 Integration of mental ray 


either sequentially or while rendering. Modifications to existing scenes, possibly after they 
have been rendered already, are called incremental changes, as opposed to recreating the 
next frame to be rendered from scratch. Specifically: 


{ Sequential incremental changes between renders are supported with dirty flags for 
certain element types that tell the preprocessing stage (see below) what to redo. 


{ Certain element types that form the DAG topology (instances, leaf instances, groups, 
functions, objects, lights, and cameras) have reference counts that are used to delete 
the element when the last link to it is broken. 


e Group 3 
Management of scene preprocessing. Scene keeps track of modification operations and 
provides a scene preprocessing function that converts the scene DAG into a renderable 
representation. This includes 


{ forwarding modified database elements to other hosts on the network, 
{ instancing including multiple instancing, 


{ inheritance of material parameters stored in instances using a custom inheritance or 
traversal?’ function provided by the caller, 


{ tessellation or re-tessellation of source geometry into triangle boxes (the Scene module 
attempts to re-use tessellated geometry whenever possible to reduce the amount of 
processing to be done from one frame to the next), 


{ calling geometry shader functions for dynamically creating source geometry, and 


{ collection of renderable geometry. 


The term instancing indicates that geometric objects and lights can be stored once, but appear 
multiple times in the rendered scene. This is implemented by storing the scene as a hierarchy 
of instances that refer subtrees, geometry, or lights. If multiple instances refer the same element, 
directly or indirectly, that element is said to be instanced multiple times. When traversing the 
hierarchy, the Scene module supports programmable inheritance of shader parameters such that 
higher levels of the hierarchy can pass shading parameters down to lower levels. The exact 
method of inheriting information is programmable, using an inheritance function that combines 
the “parent” parameter block and the “child” parameter. The parameters being inherited this way 
follow the same rules as standard shader parameters. Shaders have access to both their standard 
static parameters, and to the inherited parameters. 


mental ray 3.1 introduces traversal functions that replace inheritance functions. Both are basically 
equivalent, except that traversal functions have access to the entire instance being inherited, and 
also receive a traversal graph history list from the root group down to the current instance. This 
gives the function more control, for example over material inheritance. The inh_is_traversal?'' 
flag in the options block controls whether the function is an inheritance function or a traversal 
function. 
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5.3.4.2 SCENE vs. API 


The high-level API module provides an interface to the scene database on a higher level than the 
standard low-level SCENE interface. It is patterned after the .mi2 language; most .mi2 constructs 
have direct high-level API call interface equivalents. The following table contrasts the SCENE 
and high-level API (abbreviated API in this document) interfaces: 


SCENE 


based on struct manipulation based on .mi2 entities 
optimized for rendering optimized for scene definition 
static element sizes dynamic element sizes 


avoids reallocation and copying | reallocation and copying 
internal links by tag internal links by name 
higher porting effort low porting effort 

no output shader support full output shader support 


Based on struct manipulation means that the SCENE module provides allocation functions for 
the various database element types. All operations are done in terms of these data structures. If an 
element such as a geometric object consists of multiple data structures, the caller must separately 
allocate and combine them. In contrast, API operates on .mi2 element level, which means that 
entities such as geometric objects are defined as a unit, and that the implementation details are 
handled automatically. 


Optimized for rendering means that SCENE data structures are designed for optimum rendering 
efficiency, not for simplicity or ease of access. API follows scene structuring elements and is very 
easy to use. API does introduce some minor overhead during scene construction but not during 
rendering. 


Static element sizes means that variable-sized database elements such as vertex lists must be 
preallocated with the correct size. The number of components must be known in advance. 
Reallocation is possible but expensive in terms of speed and memory fragmentation. The API 
module buffers the components of variable-sized entities in linked page lists and allocates the 
database entry when the definition of an element is complete. 


Avoiding reallocation and copying is a consequence of the previous point. SCENE requires 
preallocation of data structures, so that after preallocation the data can be written directly into 
database memory. API buffers data, which implies temporary data structures for some entities 
and a copy operation from the buffers to database memory. This can make API slightly slower 
than SCENE for very large geometric objects. 


Internal links by tag means that SCENE will return a 32-bit identifier called a tag whenever a 
database element is allocated. To link two database elements, such as attaching a vertex list to a 
geometric object, the tag is either written into the parent element, or a special link call is used 
(depending on what type of link is formed). API does not use tags for scene elements; all entities 
have a name and links are established by name. However, API uses tags for functions (shaders) 
because functions are normally unnamed. 
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Higher porting effort results from the fact that whenever internal data structures are changed 
there is a higher probability that code using these data structures must be changed also. API calls 
are highly stable, and new features are provided in an upward-compatible way by providing new 
access functions that require no change to code that uses the existing functions. 


5.3.4.3 The Scene DAG 


All geometry is stored in a scene DAG (directed acyclic graph) that is built from groups and 
instances: groups are a container nodes that list multiple child instances. Instances are used to 
place elements in 3D space (namely, groups, geometry objects, lights, and cameras). Instances 
contain a transformation matrix that converts from the parent space to local space, placing its 
child relative to its parent, and its inverse. Optionally, it may reference a transformation function 
that defines the transformation at runtime, and it may reference a material that is used for material 
inheritance. 


The scene DAG also allows multiple instancing. This means that two or more instances may 
reference the same group, object, or light. The effect is that the referenced element appears more 
than once in the rendered image, at different locations determined by the instance transformations. 


The Scene module offers two operations that are required for rendering begins, as part of a process 
called preprocessing. One is to convert the DAG with multiple instancing to a leaf instance list, 
such that there is one separate instance for every geometry object instance in the scene. It is then 
possible to evaluate the leaf instances in sequence to generate a complete list of geometric objects 
and lights. The transformations in the leaf instances of the preprocessed tree are composed from 
all parent transformations all the way back to the root of the tree; they convert between object 
and camera space. Parameter inheritance is also evaluated. This involves propagating materials or 
other user data down the tree during traversal according to programmable rules, and storing the 
end result in the leaf instances where it can be accessed by shaders. Parameter inheritance allows 
instancing an object in different places with different surface material properties. 


The second main operation during preprocessing is tessellation. In the DAG, geometry may be 
stored as free-form surfaces and polygons, which are not directly renderable. Rendering always 
operates on triangle geometry stored in boxes. The conversion from surfaces and polygons to 
triangle boxes is called tessellation. The Scene module uses dirty flags to keep track of which 
instances, transformation functions, and geometry objects in the scene DAG have been created 
or modified since the last tessellation, and retessellates only objects that have been modified or 
transformed. After tessellation, every leaf instance references a box (or box chain if the object is 
too large to fit in one box). 


If an instance has a geometry shading function list attached, this function list is called during 
preprocessing. The geometry shaders return a scene element tag which is put into a group attached 
to the instance. This group is used for initialization of the source geometry in the DAG object. 
In addition, each material of an object is checked for geometry shaders to be called. All resulting 
dynamically created objects are put into a group attached to the object. This dynamically created 
source geometry is scheduled for tessellation in the same way as non-geometry shader objects. 


Instancing requires that the renderer operates with object coordinates, not camera coordinates. 
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This allows the Scene module to have multiple leaf instances, each with a different matrix, share 
the same box list. This happens if the object from which the boxes are derived was multiply 
instanced. Multiple instancing will fail for camera-space renderers because all instances of a 
multiply-instanced object will appear in exactly the same location in 3-space. 


© oro 
<> instance 
> | object 
/\ box 
reel 
<| camera 


Lobe 


Source DAG 


When this DAG is preprocessed, leaf instances for lights and objects are attached to the DAG 
(shown here as dotted arrows) The original DAG remains unchanged except for cached boxes 
(1c1 and 1c2) attached to objects. 
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root 


camera light list object list 


———> _ regular internal DAG links 
bine 3 > links from the renderable representation to the DAG 
------= sequential lists for rendering, anchored in the control structure 


Preprocessed DAG 


This diagram shows that preprocessing produces two new lists: the light list and the object list. 
For clarity, an instance referencing more than one child is shown with two arrows leaving at the 
bottom; this is really implemented with child/sibling links. Groups contain real child list arrays. 
All arrows are tag links, not pointers. All instances referenced by dotted arrows are leaf instances. 
Because instances 2 and 3 both reference group 2, multiple instancing occurs and both light 2 
and object leaf instance 7 with its boxes are duplicated into a and b versions. a is the result of 
instance 2, and b is the result of instance 3. (Because of the object-space restriction, 1a1 and 1b1, 
and also 1a2 and 1b2, are identical; Tags 1a1 and 1b1 are identical and so are 1a2 and 1b2.) The 
diagram shows a situation where object 1 is too large to fit in one box and needs two boxes for 
each instance. 
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The boxes 1c1 and 1c2 attached to instance 7 are called cached untransformed boxes for object 
1. This list is optional. The preprocessing function can be told to make a copy of the reference 
to the results from a tessellation before transforming the boxes and attaching them to the leaf 
instances. This increases memory usage after rendering completes because boxes are not deleted 
during postprocessing, but it avoids retessellation of the same object if the object is instanced 
multiple times or if the scene is rendered multiple times with different transformations. Again, 
note that 1al, 1b1, and 1cl are all the same box, and 1a2, 1b2, and 1c2 are all another box, so that 
only two boxes exist in memory. 


The new leaf instance contains a transformation matrix (which is optionally applied to the vertices 
in the boxes by preprocessing) and a material field, both of which are created by combining 
transformations and material fields during descent from the root group. This means that the 
leaf instances 7a and 7b likely have different transformations and/or materials because they are 
descended from different instances, 2 and 3. Transformations are combined using transformation 
function evaluation (if present and enabled) and matrix multiplication. Materials are combined 
by calling an inheritance function or traversal function’! specified by the options block. A 
“material” in this context need not be a simple material tag; it is an arbitrary-sized user field that 
can store more information such as textures or colors, or material editor flags. For such non- 
simple user fields, it is the responsibility of the inheritance or traversal?’ function to properly 
propagate different user field members. It is called for every new instance encountered during 
traversal, and is called with both the parent parameters (none for the top-level instances) and the 
current instance. 


5.3.4.4 Group 1: Database Element Management 


void *mi_scene_create( 
miTag *tag, 
miScene_types type, ...) 


creates a database element of a specified type, and provides defaults. For database elements that 
have a variable size, one or more arguments specify the sizes of the variable sections. There are 
no arguments to store specific values in the new database elements; instead, a pointer is returned 
that can be used to fill in the data. The tag of the new element is also returned. mi_scene-_create 
always returns a valid pointer; allocation errors abort with mz_fatal. If the created element is an 
instance or an object, set its dirty flag. 


void *mi_scene_recreate( 
miTag *tag, 
miScene_types type, ...) 


This function is equivalent to mi_scene-_create, but it expects tag to point to a valid tag number. 
The item will be deleted, and the new item will be created with this tag instead of choosing a new 
tag. This function is used for some types of incremental changes. 
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void *mi_scene_edit ( 
miTag tag) 


If the database element must be changed (as part of an incremental change), this call must be used 
to obtain a pointer to it. The DB call mi_db_access may not be used for this purpose, because 
Scene needs to keep track of edited elements to properly preprocess them before rendering starts. 
mi_scene_edit always returns a valid pointer; allocation errors abort with mi_fatal. If the edited 
element is an instance or an object, set its dirty flag. 


void *mi_scene_growedit ( 
miTag tag, 333) 


This call is a variation of mi_scene_edit. It is used instead of mi_scene_edit if the modification 
requires an increase or decrease of the size of one of the sections of a variable-sized element. 
The size arguments have the same order as the arguments given in the mi_scene-_create call. After 
the edit is complete, mi_scene_edit_end must be called. mi_scene_growedit always returns a valid 
pointer; allocation errors abort with mi_fatal. Note that resizes are inefficient and should be 
avoided. If the edited element is an instance or an object, set its dirty flag. 


void mi_scene_edit_end( 
miTag tag) 


After the incremental change of an element has completed, this function completes the edit. The 
pointer returned by mzi_scene_edit is invalidated. Scene handles all pinning, flushing, and updates 
of expanded DAG elements (see functions in group 2). 


Note that there are special Scene functions for accessing database elements that need to be written 
to, but no functions to access elements that are only read. For reading, the standard mi_db_access 
and mi_db_unpin functions are used. It is very inefficient to use mi_scene_edit for read-only 
accesses, and illegal to use mi_db_access for write accesses. There is no need to ever call mi_db_ 
flush, this call is for use by the Scene module only. 


Note also that the element delete function is in group 2, because it recursively deletes the subtree. 
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The Scene module supports the following types, defined by the miScene_types enumerator: 


miSCENE_FUNCTION_DECL | miFunction_decl | function declaration 
miSCENE_FUNCTION miFunction function call 


miSCENE_MATERIAL miMaterial material 
miSCENE_LIGHT miLight light 
miSCENE_CAMERA miCamera camera 


surface basis list 
geometry object 
renderable primitives 
line stripes 

instance node 

group of instances 
render options 

frame buffer definition® 
image frame huffer 

list of polygons 

index list for polygons 
same, but miGeoIndex’s 
vertex list for polygons 
same, but miGeoIndex’s 
vector list for polygons 
same, but miGeoVectors 
surface geometry list 

patch or texture surface 
curve list 

curve control point list 
curve or surface scalars 
same with high precision 
algebraic patch list 

used for box and string lists 


miBasis_list 
miObyject 
miBox 
miLinebox 
milnstance 
miGroup 
miOptions 
miFb_info 
milmg-image 
miPolygon[] 
milndex[] 
miGeoIndex[] 
milndex[] 
miGeoIndex{] 
miVector[] 
miGeoVector{ | 
miFace[ ] 
miSurtace| ] 
miCurve | 
miCurve_point[] 
miScalar[] 
miGeoScalar[] 
miAlgebraic[] 
milag[] 


miSCENE_BASIS_LIST 
miSCENE_OBJECT 
miSCENE_BOX 
miSCENE_LINEBOX 
miSCENE_INSTANCE 
miSCENE_GROUP 
miSCENE_OPTIONS 
miSCENE_FBINFO 
miSCENE_IMAGE 
miSCENE_POLYGON 
miSCENE_INDEX 
miSCENE_GEOINDEX 
miSCENE_VERTEX 
miSCENE_GEOQVERTEX 
miSCENE_VECTOR 
miSCENE_GEOQVECTOR 
miSCENE_FACE 
miSCENE_SURFACE 
miSCENE_CURVE 
miSCENE_CURVPNT 
miSCENE_SCALAR 
miSCENE_GEOSCALAR 
miSCENE_ALGEBRAIC 
miSCENE_TAG 


4 


miSCENE_STRING char[] generic ASCII strings 
miSCENE_SPACECURVE muSpacecurve[] | space curve 
miSCENE_BOOK miBook book 

miSCENE_PAGE miPage page for books 


subdivision surface 
user-defined custom data blocks 
IES/Eulumdat light profile?! 


miSCENE_SUBDIVSURF 
miSCENE_USERDATA 
miSCENE_LIGHTPROFILE 


miSurt_subsurf[] 
char[] 
miLight_profile 
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There are several additional codes that are used by mental ray internally for temporary cached 
data. When one of these database element types is created or resized, the size must be given as a 
varargs list that depends on the type: 


variable argument list for create/growedit 


miSCENE-FUNCTION_DECL | int declsize, int nsubtags 


miSCENE-FUNCTION 
miSCENE_BASIS_LIST 
miSCENE_ BOX 


miSCENE_INSTANCE 
miSCENE_GROUP 
miSCENE_IMAGE 
miSCENE_-POLYGON 
miSCENE_INDEX 
miSCENE_VERTEX 
miSCENE_VECTOR 
miSCENE_GEOVECTOR 
miSCENE_FACE 
miSCENE_-SURFACE 
misCENE CURVE 
miSCENE-CURVPNT 
miSCENE_SCALAR 
miSCENE_ALGEBRAIC 
miSCENE_STRING 
miSCENE_TAG 
miSCENE.SPACECURVE 
miSCENE_BOOK 
miSCENE PAGE 
miSCENE_SUBDIVSURF 
miSCENE_USERDATA 


miSCENE_LIGHTPROFILE 


int parmsize ! 


int nbases, int nscalars 

miVector_list *, miVertex_content *, int nvert, npri, 
enum miBox-_type type, miBoolean moving ” 
int nuserbytes ° 

int nlinks, int nconnects * 

milmg_type type, int width, int height 
int npolygons 

int nindices 

int nvertices 

int nvectors 

int nvectors 

int nfaces 

int nsurfaces 

int ncurves 

int npoints 

int nscalars 

int nalgebraics 

int nchars 

int ntags 

int nspcurves 

int line_size, int no_lines, char *swap 
int page_size, int line_size, char *swap 
int nsdsurts 

int nbytes 

int nvert, nhorz 


The parmsize parameter assumes that the shader has no ghost parameter block. To add such 
a block, pass a size twice as large as needed for the parameters, and adjust the parameter_size 
field in the created or resized miFunction afterwards. 


The type specifies the type (and hence the size) of the primitives of the box. Allowed values are 
miBOX_TRIANGLES and miBOX__ALGEBRAICS. Although vect and vert are stored in the box when 
creating or resizing, only vect—no_vectors and vect—sizeof_vertex are used for calculating the 
box size. Resizing a box does not shift box sections; the box contents except the header remain 


unchanged. 


The user bytes are intended for parameter information that is inherited down the DAG, either 
by default or by an inheritance function or traversal function’! provided by the scene. 
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* The nlinks and nconnects parameters are hints only. If more children are added with mi_scene- 
link, the Scene module will resize the group automatically if necessary. However, resizes are 
inefficient and should be avoided by giving an approximate number of links when creating the 


group. 


miBoolean mi_scene_check( 
miTag tag) 


void mi_scene_checkall ( 
miTag tag) 


Do consistency check of a database element, and print mi_debug messages for every problem 
found. If no problems are found, miTRUE is returned. The mi_scene_check function checks only 
the given element, while the mi_scene_checkall function recursively checks all sub-elements too. 
If a database element of type miObject is checked, all geometric sub-elements linked to the 
object (faces, surfaces, curves, bases, and polygons) are also checked because the check can be 
much more thorough if the cross-dependencies (such as index bounds) can also be checked. This 
function can be slow and should be used only for debugging. 


miBoolean mi_scene_dump( 
miTag tag, 
int verb) 


Print a recursive dump of the database graph beginning at tag, using the mi_info message printing 
function (which means that the verbosity level must be at least 4). The verbosity verb ranges from 
0 to 4, printing progressively more information. This function is useful for debugging. 


char *mi_scene_type_name ( 
miScene_types type) 


Return the name of a SCENE data type. For example, when passed the type miSCENE_OBJECT, it 
returns the string "object". The returned string may not be written to, and need not be released 
(it points to a static array). This function is useful when writing debugging code or error messages. 


5.3.4.5 Group 2: Scene DAG Construction 


Group 2 functions establish relations between scene elements and keep reference counts. The 
link/unlink functions and the reference counts maintained by them are intended purely for 
maintaining multiple instancing. They are not general-purpose constructors that guarantee DAG 
consistency because they would then have to know about every tag in the scene, including shader 
parameter tags, and they would have to be granted a monopoly on tag manipulation. This was 
considered too restrictive. 
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The Scene module keeps reference counts for elements that define the DAG topology (groups, 
instances, objects, boxes, lights, and cameras) to make sure that they are deleted only when the 
last parent (instance, group, object, box, or function) is deleted. The fact that boxes have reference 
counts is not visible to the caller, it is done for Scene’s own evil purposes. Other elements, such 
as lists attached to objects or shader parameters, keep no reference counts. For example, it is an 
error to reference the same polygon list in multiple objects because it would be deleted when one 
of these objects were deleted, leaving the other tag dangling. The Scene module does not keep 
backreferences, the caller is responsible for cleaning up tags that refer to the deleted element. 


void mi_scene_link( 


mitag ptag, 
miTag ctag, 
int which) 


Linking creates a parent-child relationship; ctag is linked to a new parent ptag. In the following 
table, there is one row per target item with a list of items that can be linked to it. A numerical 
digit means mi_scene_link must be used with for making the link, using the given number for 
the which argument. “M” means the tag is written manually, and “—” means no such link can be 
made. 


| sdf aims) grp) scam stig =mtl fne del box obj 


instance 


group 


camera 


light 


material 
func 

func decl 
box 

object 
sub-object 


Links to substructures of objects (called sub-objects: polygons, faces, curves, scalar lists, bases 
etc.) are always written manually. So are tags written into shader parameters. Links to instances 
attach a child, not a parent, except for functions which are taken to be the transformation function. 
miConnects must be created manually. 


Warning: linking a tag to a group may change the address of the group item in memory. A pointer 
to the group acquired with mi_db_access may become invalid. SCENE will print a warning using 
mi_debug in this case. 
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void mi_scene_unlink( 


miTag gtag, 
miTag otag, 
int which) 


This call undoes the link created by a call to mi_scene_link with the same arguments. Only the 
gtag element is affected, nothing is deleted. 


void mi_scene_delete( 
miTag tag) 


Deletes the database element tag, provided that its reference count is O or less. The reference 
count of an element is incremented when it is linked to another element using mz_scene_link, and 
decremented when it is detached from another element using mi_scene_unlink. 


If the element contains certain types of sub-tags that define the tree topology, these sub-tags are 
deleted recursively. This includes leaf instances and their child elements. Function declarations, 
materials, lights, images, and cameras are exempt; they are never deleted during recursion. If a 
function (or a material referencing a function) is deleted, the function parameters are not scanned 
for tags. Neither are group connection lists because connections may only specify children of the 
same group, which are deleted recursively. 


The following table contains one row per element type to be deleted. Each “D” in a row means 
that if the element named in the leftmost column is deleted, the sub-element corresponding to 
the column with the “D” or “d” is recursively deleted, too. Again, sub-objects are geometric 
structures referenced by objects, such as polygons, faces, bases etc. 
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void mi_scene_delete_one( 
miTag tag) 


This function is equivalent to the standard delete function above, but if a group is deleted, the 
group members are not deleted recursively, and if an instance is deleted, the instance is not deleted 
recursively. That is, in the above table only “D” tags are recursively deleted, but not “d” tags. 
This is used for the delete statement in the mi2 scene format. 


5.3.4.6 Group 3: Preprocessing 


Preprocessing prepares the scene DAG for rendering. After rendering completes, a postprocessing 
function reverses changes to the DAG done by preprocessing. Rendering must always be 
bracketed by preprocessing and postprocessing to convert the scene to a renderable format. 
None of these functions are normally used directly; use the mi_rc_run function instead which 
allows much better control over all stages of processing. These functions are deprecated and may 
disappear in future versions. 


miBoolean mi_scene_preprocess ( 
miScene_preprocess *control) 


Convert the scene DAG to a renderable representation, according to the instructions in the 
control structure. The control structure specifies the root group of the DAG, the camera instance, 
and other control parameters. Return miFALSE if preprocessing failed. 


void mi_scene_postprocess( 
miScene_preprocess *control) } 


Undo the changes done by preprocessing, such as releasing allocated memory. The leaf instances 
and boxes stay intact. The control structure is expected to be unchanged from the preprocessing 
call. 


miBoolean mi_scene_tesselate( 
miScene_preprocess *control, 
miBoolean lineboxes) 


Build a list of leaf instances that reference triangle boxes (if lineboxes is miFALSE) or lineboxes 
(if lineboxes is miTRUE) for the scene given by the root group in control. This is similar to scene 
preprocessing, except that the scene graph is not touched in any way — no boxes are cached and 
no caches or dirty flags are used or changed. Object and instance visibility, shadow, and trace flags 
are ignored. The result of this call is a leaf instance list that the caller must release (by calling mz_ 
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scene_delete on each leaf instance). This function is intended for fast wireframe previews of small 
scene subsets with no internal instances, and for on-the-fly tessellation of geometry parameters of 
geometry shaders, but not for actual rendering. Return miFALSE if tessellation failed. Geometry 
shaders are not evaluated. 


void mi_scene_set_masterhost ( 
miUint host) 


*-! By default scene preprocessing is executed on host 0. A different host can be selected by 
making calls to this function. This function must be called after the Scene module is initialized, 
otherwise an error message is printed and the ost parameter is ignored. This function is no 
longer available in mental ray 3.x because job management has obsoleted the relay library design 
of mental ray 2.x. 


miSCENE_PREPROCESS_CONTROL_INIT ¢ 
miScene_preprocess control) 


This macro initializes the control structure with default values. All fields are zeroed, except the 
tessellate flag, which is set to miTRUE. The control structure has the following fields: 


typedef int (*miInh_func) (void **, void *, int, void *, int, 
struct miInstance *, struct milnstance *, 
miMaterial *); 

typedef struct { 


miTag root_group; 
miTag camera_inst; 
miTag options; 

char object_space; 
char render_space; 
miCBoolean spare [2]; 
miBoolean cache_boxes; 
miBoolean delete_objects; 
miBoolean tessellate; 
double time; 

miPointer inheritance_func; 
int no_lights; 

int no_leaf_insts; 
int no_boxes; 

miTag lights; 

miTag leaf_insts; 
miTag boxes ; 


} miScene_preprocess; 
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The first block must be set up by the caller of mi_scene_preprocess. The fields have the following 
function: 


e root_group is the tag of the root group of the scene DAG. 
e camera_inst is the tag of the camera instance to be used for rendering. 
e options is the tag of the rendering options. 


e object_space is one of ’w’, ’?c’, or ’0’, which informs the Scene module that objects 
coordinates are stored in world space, camera space, or object space, respectively. 


e render_space is either ’c’ or ?0’, which informs the Scene module that the renderer expects 
object coordinates to be in camera or object space, respectively. Scene will create matrices 
that transform the renderable geometry. object_space and render_space should agree. No 
geometry is changed, the space fields only control the way the leaf instance matrices are 


built. 


e cache_boxes has an effect only if object_coords is false. If it is true, the raw boxes resulting 
from tessellation of objects are retained and attached as “cached untransformed boxes” to 
the instance that refers to the object. Cached boxes are used when an object is found to 
need retessellation during preprocessing; retessellation is skipped and the cached copy is 
re-used. This speeds up preprocessing, but in the worst case the memory requirements for 
the scene are doubled. 


e delete_objects specifies that all geometric objects in the scene should be deleted during 
preprocessing. This can greatly reduce memory usage, but it means that all modified or 
transformed objects must be retranslated for the next frame. If the cache_boxes flag is 
also true, objects that are only retransformed but are otherwise unchanged need not be 
retranslated because thje cached untransformed boxes still exist (if they have not been 
destroyed by mi_scene_flushleaves). 


e tessellate specifies that the objects in the scene should be tessellated. 


e time is the time the scene tree is evaluated at. This field is passed to transformation functions 
when they are called. 


e inheritance_funcis a inheritance function or traversal function?! provided by the caller that 
implements custom inheritance modes, as described below. 


The second part of the control structure is set during preprocessing. The size and the head of the 
light list and the leaf instance lists are returned. 


If used for mi_scene_tesselate, the following fields have no function and are ignored and not 
modified: cache_boxes, delete_objects, inheritance_func, no_leaf-insts, leaf_insts, no_lights, and 
lights. 


The inheritance function that combines parameter structures stored in the instances, and that is 
called as a callback function by mi_scene_postprocess, has the following prototype: 
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int function( 


void *xresult, 
void *parent, 
int parentsize, 
void *child, 

int childsize, 


struct miInstance *parent, 
struct miInstance *child, 
struct miMaterial »*mtl) 


This function is expected to combine the user fields of the parent and child instances, and return 
the size of the result and a pointer to the result (which must be stored in *resu/t). The function 
must use mi_-mem_allocate for allocating the result; the Scene module will release the memory 
unless the returned result size is 0 or negative. The parent and child sizes are the sizes of the user 
field of the parent and child instances in bytes. Pointers to the parent and child DAG instances 
are also passed, as they are stored in the database, unmodified by scene preprocessing. Note that 
the inheritance mechanism never stores inherited parameters or transformations back into the 
DAG; all temporary results are held in local storage. 


Finally, a pointer to a temporary material is passed. If the function writes a nonzero function tag 
into the material shader position of this material, raylib will store this material in the generated 
leaf instance, not the one inherited in the normal way. This gives the inheritance function control 
over individual material components, instead of inheriting complete monolithic materials. This 
is used by CATIA’s aspect inheritance mechanism. 


The main purpose of preprocessing is the creation of the leaf instance list, which represents the 
renderable geometry. This leaf instance list has a similar function as the display lists found in 
systems like OpenGL: a flat list with resolved transformation matrices used for placing objects, 
lights, and cameras in the scene. They also make it unnecessary to modity the original scene graph 
in any way to prepare it for rendering. Leaf instance lists exist only between preprocessing and 
postprocessing; they are rebuilt for every frame. 


mental ray 3.1.2 replaces inheritance functions with traversal functions. Inheritance functions can 
still be used but are deprecated; mental ray will assume inheritance function mode if the inh_ 
is_traversal’' field in the options block is false and traversal function mode if the field is true. 
Traversal functions have this prototype: 


typedef miBoolean (*miTraversal_func) ( 


void *xdata, /* opaque this pointer */ 
struct milnstance *parent, /* previously inherited instance */ 
struct milInstance *inst, /* new instance to be inherited */ 
miTag *path, /* path, begins with root group */ 

/* and ends with curr DAG instance */ 
int pathlen) /* number of tags in path[] */ 


The data pointer is always 0 if the traversal function was installed in the options block. If it was 
installed with m1_rc_run_traversal_ch, a constant opaque pointer may be defined. 
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The traversal function receives the previous instance parent (which is 0 at the top of the tree), 
the current instance found during traversal inst, the tag path path leading from the scene root 
group to the current instance, and the number pathlen of tags in path. The instances parent and 
inst are not scene DAG instances but “temporary” leaf instances created by mental ray. The inst 
instance 1s mental ray’s “proposal” for the result of the inheritance, which can be overridden by 
the traversal function by altering zmst’s fields. The parent instance is the same pointer that was 
passed to the traversal function as inst one level up in the scene graph hierarchy; this can be used 
to implement top-down inheritance by overwriting fields in zmst with fields from parent. 


When traversal reaches the bottom of the scene graph hierarchy, the leaf instance passed to the 
last traversal function for this branch becomes the leaf instance used for rendering. 


5-3-5 Database Module (DB) 


5.3.5.1. Introduction 


The database is acommon repository for data. The most important application is the scene data, 
but it can keep auxiliary data such as function declarations and frame buffers. The DB module has 
calls to create a database item, to destroy an item, to get a pointer to an item (access), to give back 
(unpin) a pointer, and to write back changes into the distributed database after writing (flush). 
All items have a unique identifier, called a tag, that is assigned by the DB module when an item 
is created. All other functions reference items through tags. Tags, unlike pointers, are unique on 
the network and can be stored in the database as part of items, thus allowing users to grow trees 
of items. 


An item is retrieved from the database by requesting a pointer to the data. The DB module 
makes sure that the requested item is in local memory, pins it, and returns a pointer to it. Pinning 
means that the DB module retains the item in memory until it is explicitly unpinned. One of the 
fundamental design goals is that data never exists twice in the same address space. All changes 
made to the item by using the returned pointer are immediately visible to all others in the local 
address space. It is the supervisor’s responsibility to make sure that no conflicts occur, such as 
modules changing the scene while it is being rendered. (The supervisor is the module that started 
the whole operation, usually a translator.) 


Creating an item and requesting a pointer as described above implies pinning the item in memory, 
so the returned pointer is guaranteed to remain valid. While an item is pinned, the DB module 
will not destroy or move the item to make space for other items coming in from the network. 
If the pointer is used to change the item (which is usually the case after creating it), the item 
must be flushed explicitly after the change is complete. Flushing means that all other hosts on the 
network who have a copy of the item are notified to delete the item from their local memory, or 
re-read it if it was pinned locally. The DB module does not offer locking functions. If a write to 
the database must be done atomically, messages must be used to implement a lock. 


Note that the DB functions that create, resize (grow), or delete DB elements should not normally 
be used by an application. Instead, the scene should be built with API calls. For certain operations, 
such as editing geometric objects, SCENE calls can be used. SCENE adds data type management, 
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including size calculations and appropriate defaults for struct fields, and dirty flag management 
for consistent virtual shared database access required when rendering on a network. API adds 
symbol table management which is necessary to construct cohesive scenes. 


5.3.5.2 DB Calls 


void *mi_db_create ( 
miTag * const’ tag, 
const int type, 
conet: anit size) 


Create a data item with the specified size, and return a nonzero tag and a nonzero address (if 
size is 0, one byte is allocated to keep the item warm). Creating implies pinning. Calls mz_fatal 
and aborts on failure. The DB module always initializes new items with null bytes. The SCENE 
module offers calls to create certain database items, which must be used when available to create 
items with defaults. No module other than SCENE may call mi_db_create directly. The type 
must be specified for mi_db_type, and for debugging purposes. It must be between 1 and 255. 
See SCENE for type creation. mi_db_create is not normally used by applications that integrate 
raylib. 


miTag mi_db_copy( 
const miTag tag) 


Create a duplicate of tag and return the tag of the duplicate. The duplicate has the same type 
and size, and the same contents as the source tag tag. The duplicate is not accessed, no unpin 1s 
required. 


int mi_db_type( 
const miTag tag) 


Returns the type that was specified when the item was created. This is done when an item needs 
to be byte-swapped; every type is swapped in a different way. Type 0 is illegal. See the type list 
miScene_types for a list of predefined internal database item types. The tag must exist. 


void *mi_db_access_type ( 
int * const type, 
const miTag tag) 


Like mi_db_access and mi_db_type rolled into one. This is useful in cases where both the address 
and the type are required and two separate calls would be too slow. The returned type actually 
has a data type miScene_type but is declared as an integer to avoid a forward declaration. 
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void *mi_db_realloc( 
const miTag tag, 
const int size) 


Changes the size of an existing database item. The resized items will be unchanged up to the 
lesser of the old and the new size. If the new size is greater than the old size, the remainder 1s 
zeroed. A pointer to the resized item is returned; the caller may not use the old pointer it may 
have gotten from an earlier mi_db_create or mi_db_access on the same database item. If szze is 0, 
one byte is allocated and a valid pointer to it is returned. Returns 0 on failure. Like mi_db_access, 
reallocation increments the pin count, and there must be a mi_db_unpin for every reallocation. 
After finishing with the reallocated item, the caller must flush the item to inform other hosts of 
the change. This call is intended for the SCENE module only. All other modules should call mz- 
scene_growedit. mi_db_realloc is not normally used by applications that integrate raylib. 


void mi_db_delete( 
const miTag tag) 


Delete the item referenced by the tag. Modules that have the item pinned are seriously out of luck 
because their pointers become invalid. The item is deleted on the local host and on all other hosts. 
The caller should make sure that no other host still has this item pinned; if one does that host 
generates a warning. This call is intended for the SCENE module only. All other modules should 
call mi_scene_delete. mi_db_delete is not normally used by applications that integrate raylib. 


void *mi_db_access ( 
const miTag tag) 


Look up the tag in the database, pin it, and return a pointer to the referenced item. This is 
an extremely popular function that must execute as fast as possible. mzi_fatal is called and the 
program aborts if the given tag does not exist. mi_db_access always returns a valid pointer. If an 
item is accessed twice, it must be unpinned twice; pinned is a counter, not a flag. Translators that 
intend to modify an item must call m1_scene_edit instead; it is equivalent but sets a dirty flag for 
later scene preprocessing, and may create overlay buffers for concurrent incremental updates. 


void mi_db_flush( 
const miTag tag) 


?-! Notify all other hosts that have a copy of the item to invalidate or re-read their copy. Flushing 
is necessary after the caller finished writing to an entry. If the item was just created using mi_db_ 
create, it is not necessary to flush it because no other host can possibly have a copy, because the 
tag is only known to the creating routine. If tag is 0, no item is flushed, but all deferred flushes (if 
any) are propagated to other CPUs. Note that flushes of items created on another host are less 
efficient than flushes of items created locally. The mzi_scene_edit_end call flushes implicitly. This 
call is available in mental ray 3.0 and later but should not be used because it interferes with job 
management. 
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void mi_db_deferredflush ( 
const miTag tag) 


2-1 This call is equivalent to mi_db_flush, except that the tag may be buffered locally and sent as 
a block if either the buffer fills, or a regular mi_db_flush is called. If, for example, all materials 
are changed, it is far more efficient to call mi_db_deferredflush tor each material followed by a 
single mz_db_flush (miNULLTAG) than to call mi_db_flush for each material. This call is available in 
mental ray 3.0 and later but should not be used because it interferes with job management. 


void mi_db_unpin( 
const miTag tag) 


Unpin an item. The pointer returned by mz1_db_access or mi_scene_edit may no longer be used. 
If the last pin is removed, the DB module is free to re-use the memory, provided that it is not 
the owner of the item (i.e., this is not the host where the item was created). This last restriction 
ensures that at least one copy of the item remains on the net of DBs. It is not allowed to unpin an 
item that is not pinned; development versions will abort with a failed assertion and production 
versions will silently ignore the extra unpin. 


int mi_db_dump ( 
const miModule module) 


This is a debugging function. It dumps all known database items to mi_info, with host ID, tag 
number, address, type, number of pins, and the module that created the database item. If the listed 
address is 0, the item is not in local memory. If module is nonzero (one of the miM_ constants), 
the listing is restricted to database items created by that module; if module is 0, all database items 
are listed. 


miBoolean mi_db_swap_config( 
char *Swap_dir, 
int swap_limit_kb) 


°2This routine configures and enables swapping database elements to disk. All swap files will 
be saved in the directory swap_dir. This directory must exist; it is not created by mental ray. It 
must have read and write permissions. The swap_lim_kb argument specifies the total number of 
database bytes that can be swapped out to the swap directory. A size of zero disables swapping 
(unless overridden; see below). 


Disk swapping also considers the MI-RAY_SWAPDIR and MI_RAY_SWAPLIMIT environment variables 
and the registry entries miSWAP_DIR_REG and miSWAP_LIM_REG. The mi_db_swap-_config parameters 
override the values from the environment variable, which override the registry. If this function 1s 
called with both arguments set to 0, the environment variables and the registry values are used. 
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5-3-6 Memory Manager (MEM) 


The memory manager is a simple memory allocator like the Unix malloc package, with 
enhancements to simplify debugging. It is used by all modules that need local memory. Unlike 
the database manager (DB), the memory manager does not allocate memory that can be accessed 
on other hosts on the network. In fact, the database manager uses the memory module to allocate 
local memory, and adds a network transport layer on top of it. 


5.3.6.1 Standard Call Interface 


void *mi_mem_allocate( 
const int size) 


Accepts one argument specifying the size of the memory to allocate. A pointer to the allocated 
memory is returned. If the allocation fails, an error is reported automatically, and the program is 
aborted. This call is guaranteed to return a valid pointer (or as valid as the operating system can 
make it, see below), or not to return at all. The allocated memory is zeroed. 


void *mi_mem_reallocate( 
void * const mem, 
const int size) 


Change the size of an allocated block of memory. There are two arguments: a pointer to the 
old block of memory, and the requested new size of that block. A pointer to the new block is 
returned, which may be different from the pointer to the old block. If the old pointer was a 
null pointer, mi_mem_reallocate behaves like mi_mem-allocate. If the new size is zero, mi-mem- 
reallocate behaves like mimem_release, and returns a null pointer. If there is an allocation error, 
an error is reported and the program is aborted. Like mi_mem_allocate, mi-mem_reallocate never 
returns if the re-allocation fails. If the block grows, the extra bytes are zeroed. 


char *mi_mem_strdup( 
const char * const text) 


Allocates memory like mzmem_allocate that holds enough bytes to hold the string text including 
the trailing null byte, copy text into it, and return a pointer to the copied string. This pointer can 
be freed with mi_mem-release. If text is a null pointer, nothing is allocated and a null pointer is 
returned; in all other cases the returned pointer is valid and need not be checked for allocation 
failures. This call is faster than explicit calls to mi_mem_allocate and strcpy. 
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void mi_mem_release( 
void * const mem) 


Frees a block of memory. There is one argument: the address of the block. If a null pointer is 
passed, nothing is done. There is no return value. 


5.3.6.2 Extended Call Interface 


typedef void *(*miMem_alloc) (size_t size); 
typedef void *(*miMem_realloc) (void *mem, size_t size); 
typedef void (*miMem_free) (void *mem) ; 


miBoolean mi_mem_set_allocator( 


miMem_alloc allocfn, 
miMem_realloc reallocfn, 
miMem_free freefn) 


This call allows applications to perform unified memory management. If used, this function 
must be called as part of the initialization process of the MEM module, immediately before mz_ 
mem_init. All three parameters must be non-null. A boolean is returned, indicating whether the 
functions were installed. The default allocators are restored as part of the automatic shutdown of 


the MEM module. 


typedef size_t (*miMem_flush_cb) (size_t amount) ; 


miBoolean mi_mem_set_flush_cb( 
miMem_flush_cb flushcb) 


The flushcb argument is a callback which mental ray calls when it needs to free up memory. The 
callback takes a single parameter indicating the number of megabytes to flush, and returns the 
number of megabytes freed. 


void mi_mem_init (void) 


This function must be called as part of the initialization process of the MEM module. No MEM 
calls other than mi_mem_allocator and mi_mem_error_handler may be performed before MEM 1s 
initialized. It is not part of the mi_raylib_init call because it is necessary for mental ray to allocate 
memory earlier, for example to parse a command line or to evaluate licensing. 


void mi_mem_release_all(void) 


Frees all memory that is allocated at this time. This is intended for error recovery, see below. 
There are no arguments and no return value. After this call returns, raylib will no longer function; 
this should be used only if raylib is about to be unloaded. 
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size_t mi_mem_flush(size_t amount) 


When called, mental ray will attempt to free up the amount (in megabytes) asked for. No 
guarantees are made, and the space may be freed up asynchronously, ie. at some time after 
the call itself. The number of megabytes freed up synchronously is returned. 


Note that if the host application calls mental ray to flush, then it may immediately get called back 
through the flush callback installed with mi_mem_set_flush_cb. The host application is responsible 
for avoiding infinite recursion. 


int mi_mem_getsize(void) 


Return the total number of bytes allocated by users of the MEM module, including MEM and 
malloc overhead. The latter is estimated to be 8 bytes per allocation. On multithreaded systems 
the number may be slightly inaccurate, in rare cases even negative, because thread statistics are 
merged periodically, not continuously, to improve performance. 


void mi_mem_summary (void) 


The number of blocks and number of bytes allocated by each module, as well as a total, is printed 
using mi_vdebug, with information about size, address, and source file name and line number 
from which mi_mem_allocate and/or the last mi_mem_reallocate was called. The results may be 
slightly inaccurate as well. 


void mi_mem_dump ( 
const miModule module) 


A list of allocated blocks of memory is printed using mi_vdebug, with information about size, 
address, and source file name and line number from which mi_mem_allocate and/or the last mi_ 
mem_-reallocate was called. If memory debugging is not enabled, file and line information is 
omitted. If module is miM_NULL, all modules are included; otherwise, only the named module is 
listed. This call will typically result in an enormously large printout. The verbosity level should 
be 7 (see mi_set_verbosity and miERR_VDEBUG). 


void mi_mem_error_handler ( 
(* const handler) (void) ) 


If an error occurs, the allocation functions such as mi_mem_allocate execute the handler function. 
The error handler then has the option to clean up and exit, or return to retry the allocation. There 
is a retry limit of 1000 for a single allocation or reallocation; if the handler returns and the retry 
fails 999 times in a row mi_fatal is called. GUI-based client applications can use this to show 
a warning dialog that tells the user to make more room on the machine and then press OK to 
resume. 
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void mi_mem_check(void) 


If memory debugging is compiled in, this call checks the memory arena for inconsistencies. If 
corruption 1s detected, detailed reports are printed to stdout. 


void mi_memcheck_add( 
miModule from, 
miModule to) 


void mi_memcheck_delete( 
miModule from, 
miModule to) 


These calls are available only in debugging versions of the raylib. They arrange for calls to 
mi_mem_check to be done automatically whenever an internal module (such as MEM or API) 
is called, and when that call returns. Obviously, this can be a slow process. The from and to 
arguments specify that calls from module from to module to should be traced. Either or both can 
be miM_NULL, which is a wildcard that means “any”. Multiple calls accumulate. 


void mi_notify_add( 
miModule from, 
miModule to) 


void mi_notify_delete( 
miModule from, 
miModule to) 


These functions are also intended for debugging, and are available only in debugging versions 
of the raylib. They work like the preceding two functions, except that they print an informative 
message when one internal library module calls another, or returns. The verbosity level should 


be at least 6 (see mi_set_verbosity and miERR_DEBUG). These calls are unrelated to mi_api_notify- 
callback. 


5.3.6.3 Error Handling 


Generally, the program cannot recover from fatal errors. Memory errors are one of the most 
severe cause for fatal errors. Since it is expected that almost all calls to the memory manager must 
report an error and abort the program, the standard allocation functions of the memory manager 
perform this function for the caller, making its life much easier. If the memory manager fails to 
allocate memory, it reports an error and uses a longjmp to return to the top-level routine’s error 
recovery routine. That routine is expected to sever all network connections, delete the entire 
database, use mi_mem-release_all to clear out the remaining arena, perhaps unload the raylib, and 
return a fatal-error code to the caller. Note that no calls may be used after mi-mem-release-all 
because all previously allocated memory that those calls may need has been released at that point. 
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The memory module does not guarantee that allocation failures are detected immediately. Many 
Unices always succeed in allocating virtual memory and defer allocating real memory or swap 
until the memory is accessed. If it turns out later that no real memory or swap space is available to 
perform the access, the operating system will kill the process, or it may kill another process that 
hogs the swap. Either way, the memory manager has no control over this. This is an extremely 
rare problem. The kernel’s swap preallocation behavior can be altered by a system administrator. 


5.3.6.4 Debugging 


Special versions of the raylib have extra debugging features built in. This makes the library much 
slower but can help finding integration problems. Code that links with such a library should 
define the DEBUG macro to benefit from memory tracing outside the library. Debugging causes 
the allocation and release functions to store the _FILE__ and __LINE__ cpp macros in a structure 
describing each allocated memory block. The mz_mem_dump call and error reports can then print 
the name and line number in the C file that allocated a block of memory. 


Debug libraries also places red zones (one unsigned int at both ends) around each allocated block 
of memory, thus increasing memory consumption. mi_mem-check checks that the red zones have 
not been written to, and also checks the arena linkage pointers. If memory corruption is detected, 
detailed reports are printed to stdout. This error report will also benefit from the source file name 
and line number information stored by standard debugging. Note that memory checking is an 
expensive process that significantly slows down the program. 


5-3-7 -mi Translator (Ml) 


The .mi translator translates a file containing a scene in .mi format to an in-core scene 
representation. After every complete frame read, the control is passed so that the scene can 
be rendered. For information on the .mi file, see book1 of this series, “Rendering with mental 
ray” [Driemeyer 05]. 


void mi_mi_parse( 


char * const mifilename, 

miBoolean resume, 

Char * const incl_path, 

char * const file_name, 

char * const file_type, 

int (*getc_callback) (FILE *), 
miBoolean verbose, 

miBoolean (*frame_callback) (miTag root_group, 


miTag camera_inst, 

miTag camera, 

miTag options, 

miInh_func *inheritance_func) ) 


This function is the mainline of the MI module. It reads and parses an mi scene file, and either 
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calls a given frame callback for every completed frame it finds, or returns to the caller after every 
completed frame. 


mifilename The path of the .mi file to parse. If it is a null pointer, stdin is parsed instead 
and no file is opened. The resulting file pointer of type FILE *, either for the 
open file or stdin, is passed to the getc callback for every character to read 
(see below). 


resume If set to miTRUE a previous run of the parser is resumed after m1_mi_parse had 
returned to the caller. The value of mzfilename is ignored in that case. 


incl_path Specifies an optional directory path where include files loaded with the 
$include statement can be found. The include path is prepended to the 
given include file name if it is enclosed in angle brackets. It is not used if the 
name is enclosed in double quotes. 


filename A path that overrides the output file path given in the first file output 
statement. This is used to implement the -o command-line option of the 
mental ray executable. 


file_type An extension name that overrides the output file type given in the first file 
output statement. This is used to implement the -type command-line option 
of the mental ray executable. Examples for types are rgb or jpg. 


getc_callback The function specified by this parameter is called for every character to be 
read from the file specified by the muifilename argument or stdin. It is not 
used for header files included with $include statements; for these getc is 
used. The callback should return a single character, or EOF (as defined in 
stdio.h) for end-of-fille. 


verbose If this flag is set, verbose statements in the .mi file are ignored. The mental 
ray executable uses this to disable verbose statements in the mi file if the 
-verbose command-line option is used. 


frame-callback This argument controls what happens when the mi parser finds a render 
statement at the end of a frame definition. If set to 0, mz_mz_parse returns. If 
the return value is miTRUE, the caller is then expected to call mi_api_render_ 
params and mi_rc_run to render the frame, and then to call mi_mi_parse with 
a render argument set to miTRUE to proceed with the next frame. This is the 
recommended procedure. 


It is also possible to pass the address of a render callback, which is then called 
by mi_mi_parse when it finds a render statement. The arguments are similar 
to what mi_api_render_params provides. The callback should then render 
the scene, and return miTRUE on success or miFALSE on error. If miFALSE is 
returned, mi_m1_parse aborts parsing and also returns miFALSE. 
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void mi_mi_parse_rayrc( 
char * const incl_path, 
miBoolean verbose) 


This function finds and loads the rayrc startup initialization file. (mental ray 3.0 looks for ray3rc 
before rayrc.) It is typically called once before creating a scene in the scene database with mz_ 
mi_parse or explicit mi_api_* calls. 


incl_path An optional directory path where the rayrc file itself, and include files loaded 
with $include statements in the mi file (if 7z_mi_parse is used) can be found. 


verbose If this flag is set, verbose statements in the .mi file are ignored. It should 
be set if there was a -verbose option on the command line, which should 
override verbose statements in the .mi file. 


void mi_mi_translator( 
char *string, 
void (*xcb) (char *)) 


?-l This function is the entry point into the translator protocol mode of MI. The translator 
protocol is a standardized streaming command interface implemented by various translators that 
allows loading, translating, and rendering scenes independently of the type of translator. The 
goal is to provide a uniform interface to all translators. The mi_mi_translator call implements a 
“dummy translator” since only the mi scene description language is supported. 


To use the MI module like a translator, do not call m1_mi_parse but send commands conforming 
to the translator protocol with repeated calls to this function. Normal operation and translator 
operation can not be mixed because the regular message functions are replaced. string may contain 
only one line containing one command; all newlines are ignored. 
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string should contain the command to be executed. cb is a callback that is called with translator 
reply messages. If cb is a null pointer, printf is used instead. For a list of valid commands and 
their reply messages, see the document “Common Translator Communication Protocol”, mental 
images, 1996. The protocol supports the help command, which prints a brief command summary: 


command operation 


init 1.0 initialize translator 

exit exit translator 

help print brief command summary 
abort abort current operation 

query translator | return translator info 

query name return current scene name 
query frame return current frame number 
query output not implemented 

query caps return capability string 

query scene return root/caminst/option tag 
set output P set output file override path 
open § open .mi path S$ 

close close .mi path (no-op) 

render translate and render 
translate translate 


Support for the translator protocol has been discontinued in mental ray 3.0. (Nobody ever used 
it.) 


5.3.8 Echo Module (ECHO) 


5.3.8.1 Introduction 


The echo module contains functions to print parts or all of the scene database in .mi2 format. This 
is the reverse operation to MI/API. The ECHO module cooperates with API to extract names 
of entities. If API was used to create the scene, the echo will use these names; otherwise ECHO 
invents names. 


5.3.8.2 ECHO Types 


The following types are defined by the echo: 


typedef struct { 


miBoolean prefer_approx_polygons; /* triangles from polygons */ 
miBoolean prefer_approx_faces; /* triangles from surfaces */ 
miBoolean ascii_output ; /* non-binary output */ 


miBoolean verbatim_textures ; /* dump textures verbatim 7? */ 
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miBoolean norendercommand; /* disable rendercmd echo? */ 


miUint explode_objects; /* write objects to subfiles */ 
miTag leaf_insts; /* for prefer_approx_* lookup */ 
miBoolean nolinkcommand; /* don’t echo link statements */ 
miUint dont_echo; /* EO_* bitmap: omit these */ 
miUint dont_recurse; /* EO_* bitmap: no preregs */ 


} miEchoOptions; 


prefer_approx_polygons and prefer_approx_faces specify whether the original source geometry 
is preferred for output. If these flags are set to miTRUE, the boxes containing triangles will be 
echoed. Depending on the SCENE preprocessing control structure flag delete_objects the source 
geometry might not be available in the scene because it is deleted to save memory. In this case the 
boxes triangles will be echoed instead of the source geometry if source geometry was requested. 
The reverse case can also happen; if ECHO is called before scene preprocessing, the tessellated 
geometry might not be available so the source geometry is echoed instead, regardless of the 
preferences set in the echo options. Echoing of non-source geometry is not recommended when 
displacement or geometry shaders are used in the scene since the geometry in the boxes is already 


modified by those shaders. 


If ascii_output is set to miFALSE, the three dimensional vectors in objects are echoed in binary 
format. All other scalar values in the scene are echoed always in ascii format. 


verbatim_textures specifies whether textures should be copied into the .mi file instead of printing 
a file texture definition. Verbatim textures will increase the size of .mi files. Textures which are 
entered verbatim into the scene database either by an .mi file or by API calls are always echoed 
verbatim. 


norendercommand disables the output of the render command when set to miTRUE. 


explode_objects’** causes objects that have at least the specified number of vectors to be echoed 
to a separate file, and a placeholder object that references this file to be echoed to the main echo 
scene. The separate file names begin with autoload_, followed by the object name. This permits 
parallel parsing, but it should be used only for large objects (say, 1000 vectors) because finding 
and opening a file on disk incurs some overhead. 

leaf_insts’ must be specified in order for the approx options above to work. The tag can be 
obtained from mi_rc_run_query. The scene must have been preprocessed for this to exist. mental 
ray uses the tag to find the tessellated versions of echoed objects. 


nolinkcommand>* suppresses echoing link statements. 

dont_echo suppresses echoing certain scene element types. 

dont_recurse suppresses the subfields of certain scene element types. For example, this can be 
used to echo light instances, but not the lights being instanced because mental ray no longer 


descends through the light instance. Both dont_echo and dont_recurse are bitmaps, composed of 
the following flags: 
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#define miEO_INST_GROUP 0x00000001 /* instance of a group */ 
#define miEO_INST_OBJECT 0x00000002 /* instance of a object/box */ 
#define miEO_INST_CAMERA 0x00000004 /* instance of a camera */ 
#define miEO_INST_LIGHT 0x00000008 /* instance of a light */ 
#define miEO_INST_FUNCTION 0x00000010 /* instance of a geom shader */ 
#define miEO_GROUP 0x00000020 /* group of instances */ 
#define miEO_OBJECT 0x00000040 /* geometric object or box */ 
#define miEO_CAMERA 0x00000080 /* camera */ 

#define miEO_LIGHT 0x00000100 /* light source */ 

#define miEO_MATERIAL 0x00000200 /* material */ 

#define miEO_IMAGE 0x00000400 /* pixel rectangle */ 

#define miEO_OPTIONS 0x00000800 /* options block */ 

#define miEO_FUNCTION 0x00001000 /* shader (dont_echo: named) */ 
#define miEO_FUNCTION_DECL 0x00002000 /* shader declaration */ 
#define miEO_USERDATA 0x00004000 /* user data block */ 


To echo complete scenes, set both bitmaps to 0. If they are not 0, the resulting scene is probably 
not renderable directly. 


5.3.8.3 ECHO Calls 


miBoolean mi_echo_scene( 


FILE *fp, /* file to print to */ 
miTag group_tag, /* root group */ 

mitag camera_inst_tag, /* camera instance tag */ 
miTag options_tag, /* rendering options tag */ 
miEchoOptions *options) /* echo options */ 


This function combines several ECHO calls and can be used for echoing a complete scene. The 
scene is defined by the root group group_tag, a camera instance tag camera_inst_tag and the 
rendering options options_tag of type miOptions. 


This function echoes the header, link and code statements, the rendering options, the given camera 
instance and camera, the scene DAG which is anchored at group_tag, and puts a render command 
into the .mi file which references the given parameters. 


The echoing can be controlled by specifying various options in options. Note that multiple scene 
DAGs defined in raylib can be echoed by calling this function for each root group separately. 


The scene is echoed to the file fp. This file pointer must be opened by the caller. mental ray 
writes the scene with standard stdio operations such as fprintf, so the caller may write a comment 
header first without interfering with mental ray. It is important that the file is opened in binary 
mode (fopen(name, "wb")) because otherwise binary vectors in the scene, if enabled, will be 
corrupted by carriage returns inserted by the OS. As usual, this is only a problem on Windows 


NT/2000/XP/etc. 
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miBoolean mi_geoshader_echo_tag ( 
FILE *fp, 
miTag tag, 
miEchoOptions *options) 


Print the contents of the given tag to the open file fp. In addition to the scene element, all 
dependent elements, such as subtags and declarations of echoed shaders, are recursively echoed. 
No dependent element is echoed twice. Echoing can be controlled by specifying various options 
in options. If options is null, default options are chosen. This function is primarily intended for 
debugging translators and geometry shaders. 


5-3-9 Image Module (IMG) 


5.3.9.1 Introduction 


The image module provides functions that read and write image files. Several different file formats, 
such as Softimage PIC, Wavefront RLA, and mental images color, scalar, and vector textures are 
supported. When creating a file, the file format is specified and a file with that type is created. 
When opening or creating a file, a subset of types (the mental images texture types) can be 
specified. If the file format differs, it is converted to and from that data type automatically. When 
reading, the file format is recognized automatically from the header (not from the file name 
extension). 


When reading or writing scanlines, the caller has to deal with only a small number of scanline 
data types. A scanline is stored in one to four arrays of components (R, G, B, A, U, V, Z, N, T). 
All components have the same depth, either 8, 16, or 32 bits. The number of components and the 
number of bits per component depends on the image type specified when opening or creating the 


file. 


The open, create, close, read, and write routines return miTRUE if the operation succeeded, and 
miFALSE if the operation failed. miimg_err_msg returns nothing, it prints a message using the 
standard mi_error function. 


Some image files are scanned top-down, others bottom-up. When reading from a file scanline- 
by-scanline, the lines will be presented in that order; when writing, the lines must be provided in 
that order. Lines are always read and written sequentially, there is no way to seek to a particular 
line (the run- length encoding of most file formats does not allow seeking). If an entire file is 
written at once, using the miimg_file_read or mi1mg _file_-write routines, IMG takes care of the 
scanline order. Either way, reading and writing is always a three-step process: first, the image 
file is opened or created; second, the image data is read or written, respectively; and third, the 
image file is closed. Reading and writing entire files is the recommended method, there is usually 
nothing to be gained by line-by-line access. 


Note that Quantel/Abekas YUV files can have only two resolutions, either 720x576 or 720x486. 
If a Quantel/Abekas file is written, it is either clipped or centered and padded with black margins. 
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YUV means the file is stored with reduced chroma resolution; this results in image quality loss. 
IMG has no functions to resize or aspect-correct images. 


5.3.9.2 Data Structures 


While a file is open, its information is stored in an miImg_file structure, similar to the FILE 
structure used in stdio. This is the primary data structure of the image module, in addition to the 
image data itself. Unlike stdio, the caller of IMG has to allocate this structure, it is not allocated 
by the open and create routines. This permits storage of error information after the file has been 
closed, and in case the open or create failed. The following file information is available in the 
miImg_file struct, after miimg_open or mi_img_create succeeded: 


int null; /* bomb out if someone forgets & */ 

[* eon een--------- public =-=------ * / 
int width, height; /* width and height in pixels */ 
int bits; /* requested bits per component, 8/16*/ 
int comp ; /* requested components/pixel, 1..4 */ 
miBoolean filter; /* caller wants filtered lookups */ 
miBoolean topdown ; /* read file top-down */ 
int filesize; /* if reading, size of file in bytes */ 
float gamma ; /* gamma correction value (read only) */ 
float aspect; /* aspect/xres*yres (for .pic output) */ 
float parms [8] ; /* additional undefined parameters, */ 

/* parm[0O] is compression quality */ 
milmg_type type; /* requested miIMG_TYPE_* */ 
miImg_ format format ; /* if reading, file format */ 
milmg_error error; /* one of miIMG_ERR_*, or O */ 
int OS_error; /* copy of Unix’s errno, or 0 */ 

[Ri Ses Sst Sendo eee private -——s<—--— * / 
int magic; /* magic number while file is open */ 
int lineno; /* current line# to be read/written */ 
miBoolean writing; /* if nz, file is open for writing */ 
miCBoolean Sswap_map; /* swap if memory-mapping */ 
miCBoolean ftype; /* actual file data type, stored as */ 


/* type + miIMG_NTYPES if current type*/ 
/* differs from best_type of format * / 


miCBoolean writable; /* writable texture (eg. light map) */ 
miUint1 dummy ; /* not used */ 

miPointer ip; /* open file descriptor, 0 if closed */ 
miPointer real_name; /* complete path (for unlink/local) */ 
miPointer convline; /* converted line if type != format */ 
miPointer data; /* more format-dependent file info */ 
char name [64] ; /* file name (for error messages) */ 


The actual definition of miImg_file contains more internal information that should not be 
accessed by other modules. gamma is available only when reading from RLA or RLB files. When 
writing or reading from other types, gamma will always be 1.0. format is one of mi IMG_FORMAT_ 
*, it can be used for determining the file format when a file is opened with type miIMG_TYPE_ 
ANY. type is a copy of the internal data type specified as an argument to mi_img_open or miimg_ 
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create. ftype is used when the current type differs from best_type of current format. This is usually 
the case for formats which support more than one data type. In this case, version 2.1 of mental 
ray sets ftype to type + miIMG_NTYPES to distinguish it from not being set; version 3.x does not 
do this. This value normally isn’t used outside IMG. The writable flag of version 3.1 is set for 
writable textures’, typically used for light mapping. 


parms provides place to supply additional parameters to miimg_create. The actual meaning of 
these values is not predefined. Currently, the miIMG_FORMAT_JPEG format interprets the first 
parameter as compression quality value. os_error fields are provided in case the application does 
its Own error reporting; normally, the miimg_err_msg call should be used for error reporting. 
Pyramidal filtering is activated if the filter field is set to mi TRUE. 


A scanline is stored in a scanline data structure. It consists of a header with four indices, followed 
by one, two, three, or four component scanlines. A component scanline is a sequence of unsigned 
chars, unsigned shorts, unsigned longs, or floats (depending on the data type) describing one 
component (red, green, blue, alpha, or whatever else the data type demands) for the entire 
scanline. Shorts are in network byte order, MSB first. The indices in the header give the offset to 
the first byte of the respective component scanline, relative to the first byte of the header. 


typedef struct { 
int e[4]: 
} miImg_line; 


The application chooses an index with one of the following constants: 


miIMG_R | red channel, 8 or 16 bits 

miIMG_G | green channel, 8 or 16 bits 
miIMG_B | blue channel, 8 or 16 bits 
miIMG_A | alpha (matte) channel, 8 or 16 bits 
miIMG_S_ | scalar, 8 or 16 bits 

miIMG_U | U vector, 16 bits 


miIMG_V | V vector, 16 bits 

miIMG_Z | Z coordinate, float 

miIMG_T | tag channel, unsigned long 
miIMG_NX | normal vector X component, float 
miIMG_NY | normal vector Y component, float 
miIMG_NZ | normal vector Z component, float 


There is no data type for which more than four of the above are valid at any time, which is why 
four indices suffice. If an index is 0, there is no corresponding component scanline; a valid index 
must always be at least equal to the size of the header (16 bytes). For example, to assign a pointer 
to the Y component of a scanline of normal vectors and then accessing the xth pixel, use 


float *normal_y = (float *)((char *)line + line->c[miIMG_NY) ; 
float ny = normal_y[x]; 
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In most cases, the image module is used to access entire images. There is a data structure that can 
be allocated by the image module that contains all scanlines of the file in one block of memory. 
This data structure consists of a global header, one scanline header for each scanline, and a list of 
component scanlines: 


#define miIMG_DIRSIZE 20 /* image filters have max 20 levels */ 


typedef struct milmg_image { 


miScalar filter; /* filtered lookups if > 0 */ 

int dirsize; /* valid # of filter levels */ 

int dir[miIMG_DIRSIZE]; /* offs from this to other imgs */ 
int width, height; /* width and height in pixels */ 

int bits; /* requested bits per comp, 8/16/32 */ 
int comp ; /* requested components/pixel, 1..4 */ 
miCBoolean local; /* local texture, use image/mmap/path*/ 
miCBoolean writable; /* writable texture (eg. light map) */ 
miCBoolean cacheable; /* cache in parts */ 

miCBoolean spare; /* unused */ 

int type; /* requested miIMG_TYPE_* */ 

miTag real_name; /* (local) file name to open */ 

int null[i]; /* unused */ 

int c [4] ; /* scanline directory */ 


} miImg_image; 


The header contains copies of the respective fields from the corresponding :fp file handle. Local 
textures do not use the scanline index array c; instead, information about the actual file is stored. 
When the image is later accesses, this information is used to read or map the file and set up the 
image pointer to point to the actual image structure that contains the image data. The component 
scanline index array is actually allocated larger; it 4 x height indices for height scanlines, not 
just for one scanline as shown. Again, the indices contain offsets from the beginning of the data 
structure to the first byte of the component scanline. There are convenience macros to access a 
component scanline. For example, to access the green component of the xth pixel of scanline y, 
use one of the following: 


(miUchar *)((char *)image + image->c[4*y + miIMG_G]); 
line_g[x] ; 


miUchar *line_g 
miUchar pix_g 


miUchar pix_g = (miUchar *)((char *)image + image->c[4*y + miIMG_G]) [x]; 


miUchar *line_g = miIMG_ACCESS(image, y, miIMG_G); 
miUchar pix_g line_g[x]; 


miUchar pix_g miIMG_ACCESS(image, y, miIMG_G) [x]; 


The access macro interprets local textures, does all the necessary indirection and accepts a 
coordinate and a component. It must always be cast to the proper pointer type if a component 
other than an 8-bit color component is accessed; by default it returns an miUchar pointer. zmage 
is assumed to be a pointer to milmg_image. (For a description of milmg-_image, see the SCENE 
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chapter.) mi IMG_ACCESS does not work on single scanlines (type miImg_line); a separate macro 
miIMG_LINEACCESS that has no middle (line number) argument is provided for that purpose. 
The macros are no longer recommended because they may become subject to texture tiling in a 
later version. Note: the miIMG_ACCESS and miIMG_LINEACCESS macros are deprecated and will 
disappear in mental ray 3.2! Shaders compiled with these macros will fail when run under mental 
ray 3.2. 


The fields filter, dirsize, and dir are used internally for pyramidal texture filtering and should 
not be accessed by other modules. With filter the magnification/minification calculation can be 
scaled if necessary. A pyramidal image structure contains a hierarchy of down-scaled images, each 
level stored in the dir field. The number of levels depends on the size of the image in the finest 
resolution. There is no restriction on the image resolutions. 


The writable’* flag is set for writable textures, which are not supported by mental ray 2.1. The 
cacheable flag is used by mental ray 3.1 internally to manage the texture cache; do not set. 


5.3.9.3 File and Data Types 


File types specify the format to be created, or the format of the file found when it is opened for 
reading. The following file formats are defined as enumerator tags of the miImg_ format typedef: 
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miIMG_FORMAT_RGB 
miIMG_FORMAT_TIFF 
miIMG_FORMAT_TIFF_U 
miIMG_FORMAT_RLA 


SGI RGB, compressed 
compressed 4-component 8bit TIFF 


uncompressed 4-component 8bit TIFF 
Wavefront RLA 


miIMG_FORMAT_RLB Wavetront RLB 
miIMG_FORMAT_TARGA compressed RGBA Targa 
miIMG_FORMAT_PIC Softimage pic, compressed 
miIMG_FORMAT_ALIAS Alias 


miIMG_FORMAT_CATIA 
miIMG_FORMAT_JPEG 
miIMG_FORMAT PNG? 
miIMG_FORMAT_HDR?:! 
miIMG_FORMAT_IFF°'! 
miIMG_FORMAT_EXR>*> 
miIMG_FORMAT_PPM 
miIMG_FORMAT_BMP 
miIMG_FORMAT_QNT_PAL 
miIMG_FORMAT_QNT_NTSC 
miIMG_FORMAT_CT 
miIMG_FORMAT_CT_H?'! 
miIMG_FORMAT_ST 
miIMG_FORMAT_VT 
miIMG_FORMAT_WT 
miIMG_FORMAT_ZT 
miIMG_FORMAT_NT 
miIMG_FORMAT_MT 
miIMG_FORMAT_TT 
miIMG_FORMAT_BIT 
miIMG_FORMAT_HT>'! 
miIMG_FORMAT_MAP 
miIMG_FORMAT_ZPIC 
miIMG_FORMAT_NULL 
miIMG_FORMAT_LWI°* 
miIMG_FORMAT_Ps>* 
miIMG_FORMAT_EPS°~ 
miIMG_FORMAT_SHMAP> 


Dassault Systemes CATIA format 
baseline sequential JPEG 

Portable Network Graphics 
Radiance 8-bit RGBE high dynamic range image 
Alias Maya color image format 

OpenEXR image format 

Jet Poskanzer’s portable pixmaps 

Microsoft BMP 32-bit uncompressed 
Quantel/Abekas, 576x720 

Quantel/Abekas, 486x720 

mi Color Texture 

mi HDR RGBE Color Texture 

mi Scalar Texture 

mi vector texture, from alpha 

mi vector texture, from intensity 

mi Z channel, from intersect depth 

mi normal vectors 

mi motion vectors 

mi tag channel, from material tags 

mi one-bit render-enable flags 

mi 8-bit RGBE high dynamic range image 
mmap-ed raw texture file 

Softimage Zpic, uncompr Z coords 

dummy file, write nothing at all 

Solidworks texture, read only 

PostScript, write only 

encapsulated PostScript, write only 

shadow map, like ZT with appended space info 
miIMG_FORMAT_CUSTOM_0 first user-defined file format 
miIMG_FORMAT_CUSTOM_15 | last user-defined file format 
miIMG_FORMAT_TIFF_3 * compressed 3-component 8bit TIFF 
miIMG_FORMAT_TIFF_U3 * uncompressed 3-component 8bit TIFF 
miIMG_FORMAT_TIFF_16 * compressed 4-component 16bit TIFF 
miIMG_FORMAT_TIFF_16_U | * uncompressed 4-component 16bit TIFF 
miIMG_FORMAT_TIFF_16_3 | * compressed 3-component 16bit TIFF 
miIMG_FORMAT_TIFF_16_U3 | * uncompressed 3-component 16bit TIFF 
mi IMG_FORMAT_CT_16 * mi Color Texture, 16 bits 
miIMG_FORMAT_CT_FP * mi Color Texture, floating-point 


miIMG_FORMAT_ST_16 * mi Scalar Texture, 16 bits 
miIMG_FORMAT_ST_FP>:! 


* mi Scalar Texture, floating-point 
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Formats marked with “*” are obsolete and should not be used in future versions. Data-dependent 
format variants are now selected with the appropriate data type. If the data type does not match 
the format, the best default type for the format is used. Custom formats must be registered with 
miimg_custom_format before they can be used. 


Available data types are the following enumerator tags of the miImg_type typedef: 


miIMG_TYPE_RGBA 
miIMG_TYPE_RGBA_16 
miIMG_TYPE_RGBA_FP 
miIMG_TYPE_RGB 
miIMG_TYPE_RGB_16 
miIMG_TYPE_RGB_FB°* 
miIMG_TYPE_RGBE>! 
miIMG_TYPE_A 
miIMG_TYPE_A_16 
miIMG_TYPE_A FP?! 
miIMG_TYPE_S 
miIMG_TYPE_S_16 
miIMG_TYPE_S_FP>:! 
miIMG_TYPE_VTA 
miIMG_TYPE_VTS 
miIMG_TYPE_Z 
miIMG_TYPE_N 
miIMG_TYPE_M 
miIMG_TYPE_TAG 
miIMG_TYPE_BIT *1 bit, bit mask 

miIMG_TYPE_COVERAGE>* | 1*32 bits, fp coverage of dominating object 


miIMG_TYPE_ANY wildcard that turns off all conversions 
miIMG_TYPE_ERROR special value for miimg_tdentify_type 


* The floating-point color format stores normal component values in the range (0,...1) but 
permits values outside that range. When such a value is converted to an 8-bit or 16-bit format, 
the value is clamped before being multiplied by 255 or 65535, respectively. 


4*8 bits, color with alpha 
*16 bits, color with alpha 

*32 bits, color with alpha, floats * 

*8 bits, color 

*16 bits, color 

*32 bits, color, floats * 

*8 bits, high dynamic range RGB color 
*8 bits, alpha 

*16 bits, alpha 

*32 bits, alpha, floats * 

*8 bits, intensity 

‘16 bits, intensity 

*32 bits, intensity, floats * 

*16 bits, bumpmap from alpha 

*16 bits, bumpmap from intensity 

*32 bits, Z coordinates (float) 

*32 bits, normal vectors (float) 

*32 bits, motion vectors (float) 

*32 bits, tag channel 


pd ek ee ty ee a 


File formats support data types, at least one default data type, called best_type; for example, a 
SOFTIMAGE PIC file could have data type miIMG_TYPE_RGBA or miIMG_TYPE RGB, and an NT 
normal vector file always has the data type miIMG_TYPE_N. In general, much more file format 
variants are accepted on input than are available for output. Output types are reduced to just the 
most useful types, like mi IMG_TYPE_RGBA or miIMG_TYPE_RGB for color images. As a special case, 
mental ray will allow storing RGBE>" data in 8-bit RGBA formats if this is explicitly requested; 
such image files are not displayable with standard image viewing programs. 


miIMG_FORMAT_MAP files are an exception; they have their own data type field in the header which 
can have any mi IMG_TYPE_* value. However, when opening a file, it is possible to specify the 
desired data type to be used when scanlines are accessed; or, when creating a file, specify the data 
type of the scanlines to be written. If these data types disagree with the data types supported by 
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the file format, the image module transparently converts the data type. Not all conversions are 


possible. 


5.3.9.4 Local Textures 


mental ray 3.0 does not distinguish local textures in the data structures in any way. They are just 
regular textures, demand-loaded like non-local textures, except that the job manager has different 
instructions for how to load them. The remainder of this section applies to mental ray 2.1 only, 
which did not have a job manager. 


Local textures are a variation of regular images in the database. A regular image consists of a 
header, followed by the component scanline index list, followed by the image data. A local image 
also begins with a header, but it has the /ocal flag set and contains no index list and pixel data. 


When a local image is used, the pointer to the DB item (returned by mi_db_access or mi-_scene- 
edit) must be “validated” by passing it through m1_img_validate_local_image*'. This function 
will either return its argument pointer if the image is not local, or it will read or memory-map the 
image into memory and return a new image pointer to it. The new image has the standard format 
and can be used like a regular image, but it is allocated in local memory and not in DB. 


The miIMG_ACCESS macro (which is deprecated and will disappear in mental ray 3.2) and the 
mi1mg_access and mi_lookup_*_texture functions implicitly validate textures and return correct 
image data or pointers. 


The purpose behind this is that textures can be very large, and sending them to other hosts can 
be expensive. A local image is a very small DB item and can be sent cheaply, putting the burden 
of decompression and reading from disk on the requester. Local image DB items contain a path 
name that must lead to the actual image file on all slave hosts. 


If the local texture is memory-mappable (i.e. has the type map), it is mapped automatically. If 
not, it is read into memory. This is transparent, no special flag in the DB item is needed to mark 
a file as memory-mappable. 


After the local image is no longer needed, it must be invalidated with a call to miimg_invalidate_ 
local image*'. This frees the allocated memory or removes the memory map. Calling mi_scene- 
delete on the DB item implicitly invalidates the local texture memory if present. It is also possible 
to invalidate all images with one call. 


5.3.9.5 Error Codes 


The image module defines a range of error codes that are used in the miIlmg_file data structure, 
using the error field. There are also os_errors, which contain the unmodified Unix error. The 
following error codes are defined, in addition to 0 (no error). A sub-format error occurs if the 
file format is recognized, but the actual encoding is not supported. For example, there may be 
multiple compression methods allowed for a format, some of which are not supported by the 
image module. 
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miIMG_ERR_READ 


can’t read, end of file 


miIMG_ERR_WRITE can’t write, probably disk full 
miIMG_ERR_DECODE file format error 
miIMG_ERR_ENCODE internal error 


miIMG_ERR_FORMAT 
miIMG_ERR_SUBFORMAT 
miIMG_ERR_CREATE 
miIMG_ERR_OPEN 
miIMG_ERR_CLOSE 


unrecognized file format 
file version not supported 
failed to create file 

failed to open file 

failed to close file 


miIMG_ERR_ARGS incorrect call argument 
miIMG_ERR_NOTOPEN file not open 
miIMG_ERR_NOTCLOSED | file still open, can’t re-open 


miIMG_ERR_SIZE the .map file has an unexpected size 


5.3.9.6 Function Calls 


miBoolean mi_img_create( 


milmg_ file *ifp, 
char *kname , 
milmg_type type, 
milmg_format format, 
int width, 
int height ) 


To create a file, a name, data type, and file format must be specified. type determines the internal 
scanline data type (c[ ] or s[ ], see m11mg_alloc) that the caller will use when it calls miimg- 
write. type must be one of the internal types; see OPEN in the next paragraph (mi IMG_TYPE_ANY 
is not allowed though). format determines the type of the file. If both are different, the data will 
be converted. When creating a file that supports multiple data types by default the best_type will 
be used. To request a different data type the ftype member of the miImg file structure must be 
set to type + miIMG_NTYPES (version 2.1 or 3.0; mental ray 3.0 also accepts type without adding 
miIMG_NTYPES). The field will be further used in the reading functions of IMG (see below). 


No file name extensions are removed or added. width and height determine the size of the image. 
left, right, bottom, and top are copied to the file header if the file format supports it, and are 
ignored otherwise. If m1_img_create succeeds (returns miTRUE), m1img_close must be called after 
all scanlines have been written. Null files can be created and written to, but no data will appear in 
the file, and it will be removed when closed. Note that the memory location to which #fp points 
should be zeroed before calling this function; the fields filter and magic are examined by this 
function, so correct initialization of them is mandatory. 
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miBoolean mi_img_open( 


milmg_ file *ifp, 
char *name , 
milmg_type type) 


For opening a file, a name and preferred type must be specified. the type must be one of the 
supported internal data formats. These types specify both the requested internal scanline data 
type (8/16/32 bits and the number of components), and the type of conversion if applicable. For 
example, miIMG_TYPE_A and miIMG_TYPE-_S act the same if the file is a scalar texture, but if the 
file is a color file with alpha, mi IMG_TYPE_A takes the alpha and miIMG_TYPE_S takes the RGB 
intensity. 


The conversion routines try to do the most reasonable thing; miIMG_TYPE_A will use the RGB 
intensity of a color file if there is no alpha available. The conversion of vector texture files to an 
internal format other than mi IMG_TYPE_VTA and miIMG_TYPE_VTS (which require no conversion) 
is dubious, it is done in a way that is not very useful except for image display programs. The same 
is true for conversions of tag channels and normal vector maps to RGB or S. If the actual data 
type found in the file is different from the type requested then the ftype member of the miImg_ 
file structure is set to type + miIMG_NTYPES. 


This can be used to check what data type really was supplied in the file. This field will be further 
used in the writing functions. If mi IMG_TYPE_ANY is requested, ifp—>format can be accessed to 
determine the type of the file; it will be one of mi IMG_FORMAT_* (see miimg_create above). ifp— 
>type will contain the suggested mi IMG_TYPE_*. Note that the memory location to which ifp 
points should be zeroed before calling this function; the field magic is examined by this function, 
so correct initialization is mandatory. It is however correct to use the 7fp initialized by miimg_ 
create continue to use ifp after mz_img_-close. 


miBoolean mi_img_close( 
miImg_file *ifp) 


After a file has been opened successfully, it must be closed to release allocated memory and file 
descriptors. It is safe to use mi_img_close on an milmg file structure for which the open or create 
failed, but it is not required. If the file has type miIMG_FORMAT_NULL, it will be deleted. 
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miBoolean mi_img_image_read ( 
miImg file *ifp, 
miImg_image * image) 


miBoolean mi_img_image_write( 
miIlmg_ file *ifp, 
miImg_image *image) 


These calls are similar to the scanline rading and writing routines, but return an entire image. 
They cannot be mixed with scanline reads or writes. The image module always stores the bottom 
line as the first scanline in the image data structure. 


miImg_image mi_img_mmap_address ( 
miImg_file *ifp) 


If the file is memory-mappable, return its address in virtual memory. This works for .map (mi IMG_ 
FORMAT_MAP) files only, all other formats return a null pointer. For this function to be successful 
the file also has to contain the correct data type and filtering as specified in ifp. It must also have 
the correct byte-sex. Should any of these requirements not be met, or the file is otherwise deemed 
unsuitable to direct use, a null pointer is returned. 


After opening or creating a file, the caller should always attempt to mmap the file. If it returns a 
non-null pointer, use it; otherwise, allocate an image buffer with miimg_image_alloc or mi_img_ 
image_dbcreate and use standard read/write calls (miimg_image_read and mi_img_image-write) 
to access the data. If the call succeeds, it is functionally equivalent to performing the other two 
calls from the user’s perspective. Memory mapping is far more efficient than standard reading 
and writing because no memory and no swap needs to be allocated, and because only the parts of 
the image actually accessed cause disk transfers. On the other hand, .map files are uncompressed 
and require more space on disk (about as much as they would consume swap if loaded). Also, 
.map files cannot be stored in the database; every host involved in the render must do its own m1i_ 
img_mmap-address. Use miimg_image_release to unmap the image after use. An image received 
from this function can be used after the file is closed as this usage example demonstrates: 


milmg_image *image; 

mi_img_open(ifp) ; 

image = mi_img_mmap_address(ifp) ; 

if ('image) { 
image = mi_img_image_alloc(ifp); 
mi_img_image_read(ifp, image) ; 

t 

mi_img_close(ifp) ; 

/* use image ... */ 

mi_img_image_release (image) ; 
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void mi_img_image_release( 
milmg_image *image ) 


Release an image pointer created with miimg_mmap_address or miimg_image-alloc. 


miImg_type mi_img_type_identify ( 
char *typename ) 


Look up the alphanumeric data type, and return the corresponding miIMG_TYPE_* code. If the 
alphanumeric type is unknown, return miIMG_TYPE_ERROR. The alphanumeric type must be all- 
lowercase. 


miImg_format mi_img_format_identify ( 
char *formatname) 


Look up the alphanumeric file format, and return the corresponding mi IMG_FORMAT_* code. If 
the alphanumeric file format is unknown, return mi IMG_FORMAT_ERROR. Upper and lower case is 
significant; "Zpic" must be spelled with a capital Z. 


milmg_type mi_img_best_type( 
miImg_format format ) 


Returns the preferred data type for the file format. The file can be read or written without 
conversion if the scanline buffer has this type. The type returned is equal to the type chosen 
by miimg_create if called with miIMG_TYPE_ANY. mi_img_best_type is useful if scanlines or 
images need to be allocated before the file is actually created. 


char *mi_img_type_name( 
miImg_type type) 


Returns the name of the specifies data type as a string. This is the reverse operation to miimg_ 
type_identify. 


char *mi_img_format_name( 
milmg_format format ) 


Returns the name of the specifies file format as a string. This is the reverse operation to miimg_ 


formatidentify. 
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miImg_image *mi_img_image_alloc( 
miImg_file *ifp) 


This function allocates a large buffer that contains enough scanlines for the entire image specified 
by the ifp argument. To release an image allocated with miimg_image-alloc, use miimg_release 
on the pointer returned by mi_img_image_alloc. The allocated image is zeroed. In order to call this 
function, ifp need not reference an open file, but ifp—>type, ifp->width, and ifp—>height must 
be defined. If the file is not open, all others must be set to 0; except for ifp—>name which may 
contain something descriptive. If zfp — filter is set to miTRUE, this function allocates an image 
pyramid structure which makes elliptical filtering faster. 


milmg_image *mi_img_image_dbcreate( 
milmg_file *ifp, 
miTag *tag) 


?-1 This function is equivalent to miimg_image_alloc. The only difference is that the image is 
created as a database item, instead of being allocated in local memory. The returned pointer can 
be used in the same way as a pointer returned by miimg_image_alloc. To destroy the item, use 
mi_scene_delete on the returned tag, not mi_db_delete or mimem_release. The database item is 
created by calling mz_db_create, which pins the item, so mi_scene_edit_end must be called later. 
This function is used only by the SCENE module; all other modules must use mi_scene_create. 
To create a new image, set *tag to miNULLTAG before calling; to reallocate an existing image, set 
it to the tag of the existing image. If zfp—filter is set to miTRUE, this function allocates an image 
pyramid structure which makes elliptical filtering faster. 


This function is recommended for mental ray 2.1 only. Use the corresponding API functions 
to create images in mental ray 3.x because only then can on-demand loading be used to reduce 
memory usage. 


miImg_image *mi_img_local_image_dbcreate( 
milmg file *ifp, 
miTag ktag) 


?-l This call is equivalent to the previous, but creates or reallocates a local image instead of a 
standard texture. Only the real_name field in ifp must be defined; it must point to the full path 
name of the local image. The path must be valid on all hosts. 


This function is also recommended for mental ray 2.1 only. Use the corresponding API functions 
to create images in mental ray 3.x. 
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miImg_image *mi_img_validate_local_image( 
miImg_image *ximage ) 


’-l Given a pointer to an image DB item that may be a local image, return an image pointer 
that points to an accessible image. If the image is not a local image, the argument is returned; 
otherwise, a different image pointer is returned. If this function is used on a local image for the 
first time, the image is read or memory-mapped from disk; all future calls until invalidation return 
the new image immediately. If validation fails because the file cannot be found or read, a null 
pointer is returned. The zmage will remain unchanged in this case. mental ray 3.0 does not need 
this function because job management causes implicit validation at every tag access. 


void mi_img_invalidate_local_image ( 
miImg_image *image) 


2-1 This is the reverse operation to the previous call. Restore the image DB item to the state it was 
in before the local image, if any, was loaded or memory-mapped. This call is used in mi_scene_ 
delete when an image DB item is deleted (do not use mi_db_delete for deleting because the local 
image memory will be lost). 


void mi_img_invalidate_local_images (void) 


2-1 The IMG module has an internal list of all currently successful memory-mapped images. This 
function unmaps all these images, making more virtual memory available. When the images are 
accessed after calling this function, they must be validated again using mi_img_invalidate_local- 
image. 


miIlmg_image *mi_img_access( 


milmg_image *image, 
int y> 
int comp, 


Returns a pointer to a component scanline of an image. If the image is a local image, validate it”. 
This call implements the mi IMG_ACCESS macro (which is deprecated and will disappear in mental 
ray 3.2); 


void mi_img_err_handler ( 
void (*cb) (milmg_file *ifp) 


Install an error handler that is called by mi_img_err_msg after printing the error message. The 
callback has the option of exiting the program with a fatal error message, or returning to proceed 
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with the program. Not installing an error handler always proceeds. This can be used to make the 
inability to find a texture file or to write an output image a fatal error for standalone processes 
but not for embedded library versions that must not kill their client application. If mzimg-err- 
msg is called and no error condition exists, the callback is not called. The callback may use ifp to 
exit only for some error codes. This call is typically used during library initialization, before mz_ 
mem_init and mi_raylib_anit. 


void mi_img_debug( 
int level) 


Turn on debugging by setting the img_debug variable. This call is intended to be used in a 
debugger, or set by a command-line front-end or an environment variable or something similar. 
See below. 


5.3.9.7 Convenience Function Calls 


In addition to the function calls in the previous section, convenience functions exist that simplify 
accessing frame buffers and performing simple operations on colors. These functions are all 
implemented on top of the (deprecated) mi IMG_ACCESS macro. All these functions do nothing or 
return defaults if the zmage pointer is 0, or if the x, y coordinate is out of bounds. They do not 
check whether the frame buffer has the correct data type. 


void mi_img_mode( 


miBoolean desaturate, 
miBoolean dither, 
miBoolean no_premult, 
double gamma ) 


2-1 Set the mode for all future mi_img_put_color and mi_img_get-color calls. This should be used 
with care, because if the arguments change between a put and a get, get will not return the 
same value stored with put. Desaturation specifies the clipping method for out-of-range color 
components: if desaturation is turned on, the color is faded to white; if it is turned off (default), 
individual components are clipped if they exceed 1. Dithering, if enabled, adds a random constant 
to each component such that the lowest bit of the quantized component is jittered to avoid 
banding. If zo_premult is true, the standard color premultiplication is undone before quantization, 
by dividing R, G, and B by alpha. If the gamma factor is not 1.0, gamma correction is applied to 
colors before quantization (floating-point and RGBE colors are not gamma-corrected). If any of 
the arguments has the integer value -1, it is ignored and not set (this requires casting). 


mental ray 3.0 has moved the flags and gamma into the options. There is still a miamg_mode 
function, but it merely passes the tag of the options structure, and it is used internally only. 
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void mi_img_getmode( 


miBoolean *desaturate, 
miBoolean *dither, 
miBoolean *no_premult, 
double *gamma ) 


?-' Retrieve the current modes as previously set with mi_img_mode*'! or the defaults. If an 
argument pointer is null, no value is stored. 


void mi_img_clip_color( 
milmg_image *image, 
miColor color) 


Applies the clipping and desaturation specified with mi_img_mode to a single RGBA color. If the 
color frame buffer img is a floating-point frame buffer, do nothing; otherwise either desaturate 
or clip the RGBA components to bring them into the range [0...1]. If any of RGB exceed A, set 
A to the maximum of RGB. Gamma is not applied, and neither is un-premultiplication because 
that is a function of quantization. Internally, raylib always works with premultiplied colors. 


void mi_img_put_color( 


milmg_image *image, 
miColor *color, 
int : 
int y) 


Store the color color in the color frame buffer zmage at coordinate x y, after performing desatura- 
tion or color clipping, gamma compensation, dithering, and compensating for premultiplication, 
if enabled by the miimg_mode call. This function works with 1, 3, or 4 components per pixel, 
and with 8, 16, or 32 bits per component. The normal range for non-floating point R, G, B, and 
A color components is [0, 1] inclusive. 


void mi_img_get_color( 


milmg_image *image, 
miColor *color, 
int 
int y) 


This is the reverse function to mi_img_put-_color, it returns the color stored in a frame buffer at the 
specified coordinates. Gamma compensation and premultiplication, if enabled by miimg_mode, 
are applied in reverse. (Note that this is done correctly only if the mzimg_put_color has not been 
called with different arguments since the corresponding call to miimg_put-_color.) The returned 
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color may differ from the original color given to mi_img_put_color because of color clipping and 
color quantization. If the frame buffer has only one component, all four components of color 
will have the same value; if the frame buffer has three components, alpha is set to 1. If the frame 
buffer pointer is 0 or if the coordinates are out of bounds, all components are set to 0. 


void mi_img_get_color_square( 


milmg_image *image, 
miColor *color, 
int a 
int y) 


This function is very similar to miimg_put_color, except that it returns four color values: Those at 
(x,y), (x+1,y), (x,y+1) and (x+1,y+1) . The parameter color must point to the array of four miColor 
structures that will receive the color values, in the order given above. This function is primarily 
intended to be used by texture lookup functions such as mi_lookup-color_texture that need to do 
bilinear interpolation of four colors. It saves the overhead of four function calls and redundant 
validation checks. Note that unlike some of the other functions, it doesn’t check the range of x 
and y, and it is up to the caller to ensure that they are in range. 


void mi_img_put_scalar( 


milmg_image *image, 
miScalar scalar, 
LH + 
int y) 


Store the scalar scalar in the scalar frame buffer image at coordinate x y, after clipping to the range 
[0,1]. Scalars are stored as 8-bit or 16-bit unsigned values. This function is intended for scalar 
texture files of type miIMG_S or miIMG S_16. 


void mi_img_get_scalar( 


milmg_image *image, 
miScalar *Scalar, 
int =; 
int y) 


This is the reverse function to m1_img_put-_scalar, it returns the scalar stored in a frame buffer at 
the specified coordinates, converted to a scalar in the range [0, 1]. If the frame buffer pointer is 0 
or if the coordinates are out of bounds, the scalar is set to 0. 
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void mi_img_put_vector ( 


milmg_image *image, 
miVector *VeCtor, 
Lit <=; 
int y) 


Store the X and Y components of the vector vector in the vector frame buffer image at coordinate 
x y, after clipping to the range [—1, 1]. Vectors are stored as 16-bit signed values. This function is 
intended for vector texture files of type mIIMG_VTA or miIMG_VTS. 


void mi_img_get_vector( 


milmg_image *image, 
miVector *vector, 
int 
int y) 


This is the reverse function to mi_img_put_vector, it returns the UV vector stored in a frame buffer 
at the specified coordinates, with coordinates converted to the range [—1, 1]. The Z component 


of the vector is always set to 0. If the frame buffer pointer is 0 or if the coordinates are out of 
bounds, all components are set to 0. 


void mi_img_put_depth( 


milmg_image *image, 
float depth, 
int x; 

int y) 


Store the depth value depth in the frame buffer image at the coordinates x y. The depth value is 


not changed in any way. The standard interpretation of the depth is the Z coordinate of objects 
relative to the camera. 


void mi_img_get_depth( 


milmg_image *image, 
float *depth, 
int x, 
int y) 


Read the depth value to the float pointed to by depth from frame buffer image at the coordinates 


x y. If the image pointer is 0, or if the coordinates are out of bounds, return the MAX_FLT constant 
from limits.h. 
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void mi_img_put_normal ( 


milmg_image *image, 
miVector *normal , 
int x; 
int y) 


Store the normal vector normal in the frame buffer zmage at the coordinates x y. The normal 
vector is not changed in any way. 


void mi_img_get_normal ( 


milmg_image *image, 
miVector *normal , 
int xX, 
int y) 


Read the normal vector normal from frame buffer image at the coordinates x y. If the image 
pointer is 0, or if the coordinates are out of bounds, return a null vector. 


void mi_img_put_label ( 


milmg_image *image, 
miUint label, 
int =. 

int y) 


Store the label value /abel in the frame buffer image at the coordinates x y. The label value is not 
changed in any way. 


void mi_img_get_label( 


milmg_image *image, 
miUint *label, 
int x, 
ant y) 


Read the label value to the unsigned integer pointed to by label from frame buffer image at the 
coordinates x y. If the image pointer is 0, or if the coordinates are out of bounds, return 0. 
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5.3.9.8 Custom File Formats 


New user-defined file formats can be registered by defining a number of functions, and specifying 
some information about the format. There are 16 slots for user-defined file formats. They can be 


defined with: 


miBoolean mi_img_custom_format ( 


milmg format format, 

miBoolean (*test) (miImg\_file * const, char * const), 
miBoolean (*create) (miImg\_file * const), 

miBoolean (xopen) (miImg\_file * const, char * const), 
miBoolean (*close) (miImg\_file * const), 

miBoolean (tread) (miImg\_file * const, miImg\_line * const), 
miBoolean (*write) (miImg\_file * const, miImg\_line * const), 
miBoolean tdown, 

char *name , 

miUint tmap, 

int btype, 

int flags) 


This function registers the new format format, which must be one of the enumeration tags in the 
range mi IMG_FORMAT_CUSTOM_O through miIMG_FORMAT_CUSTOM_15. It may not be called before 
raylib is initialized. Six C functions must be passed. All of them return miFALSE on failure and 
miTRUE on success. 


test 


create 


open 


is given the first 256 bytes of an open file to be read. It must return miTRUE if 
the file has a type understood by the read function, and miFALSE otherwise. This 
is typically done by checking magic numbers at the beginning of the file, or by 
verifying whether the information in the file header makes sense. If the file cannot 
be identified with confidence, miFALSE must be returned. It may not call any error 
functions because failure is not an exceptional event. The custom formats are tested 
early, which means that they can be used to override a built-in format. It also means 
that the test function should be careful not to incorrectly return miTRUE. 


begin a new file. The file has already been created empty on disk. Typically this 
function writes the file header, and allocates whatever variables or scanline buffers 
are required during scanline writing later. 


begin reading a file. The file has already been opened and rewound to file position 
0. Typically this function reads the entire file header, identifies the subtype (for 
example, if both RGB and RGBA variants are supported), and fails if it is not 
supported), and allocates variables or scanline buffers for reading with the read 
function later. The first 256 bytes of the file are passed as the second argument like 
for test. The width, height, comp, and bits fields of the miImg_file structure passed 
as the first argument must be set by this function. 
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close stop reading or writing the file. Normally this is the place to release all data allocated 
by the create or open calls. It may also rewind and modify the file header if required. 
The file should not be closed; this is done by mental ray. 


read read a single scanline into the scanline buffer passed as the second argument. 
Pointers to the component scanlines can be retrieved with the (deprecated) mi IMG_ 
LINEACCESS macro. 


write write a single scanline from the scanline buffer passed as the second argument. 
Pointers to the component scanlines can be retrieved with the (deprecated) mi IMG_ 
LINEACCESS macro. 


All functions may use the data field (a void pointer) of the miImg_file structure passed as the 
first argument to attach local data, such as scanline buffers or other format-specific data. If used, 
mi_mem_allocate should be used in the open and create functions to allocate a buffer, and mi_ 
mem_-release should be used in the close function to delete it. It is not a good idea to let data point 
to static storage because these functions must be reentrant. All functions except test (which fails 
silently) may use miimg_custom_format_error to report errors. 


Finally, the tdown argument should be miTRUE if the file is stored with the top scanline first, or 
miFALSE otherwise. The name is the name of the format, which is also the name of the extension. 
For example, jpg is a good name. The function imposes no restrictions, but it is a good idea to 
keep the name short (typically three or four characters), and to use only lowercase letters and, if 
necessary, digits. Do not begin with a dot, and do not use a name already supported by mental ray. 
The tmap is a bitmap of allowed data types, and should be set to the logical-OR or expressions 
like 1<<miIMG_TYPE_RGB. The btype argument must be set to the “best” type for the format. For 
example, mi IMG_TYPE_RGB is the best type for JPEG/JFIF files. This type is automatically added 
to the tmap bitmap (effectively it performs tmap |= 1<<btype). The flags argument is reserved 
for future extensions and must be set to 0. 


miBoolean mi_img_custom_format_error ( 


milmg_ file *ifp, 
milmg_error error, 
int os_error) 


This function should be used only by one of the six functions installed with miimg_custom_ 
format. It saves an error code for later printing. If a file is being written, it is deleted on disk to 
prevent partial files. After calling this function, the caller will normally return miFALSE without 
further processing. The zfp is the same that the caller got as its first argument, error is a code 
number such as mi IMG_ERR_WRITE, and os_error should have the value of the operating system’s 
errno variable if the failure was the result of a failed OS or C library function, or 0 for non-OS 
failures. See above for a list of available failure codes. The caller may also use mi_error before 
calling this function to provide more information. 


See section 5.2.5 for a detailed example. 
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5.3.9.9 Diagnostics 


mi_img_create, mi_img_open, miimg_close, miimg_read, and miimg_write return miFALSE if an 
error occurred, or miTRUE if the call succeeded. mi_img_alloc returns 0 if there is no memory, and 
a nonzero pointer otherwise. m1_img_err_msg returns nothing. All others return values, there are 
no errors. There is a global variable 2mg_debug that can be set to values 0..3 for automatic printing 
of diagnostics, and a routine m1_img_debug that sets this variable: 


no automatic diagnostics 
diagnostics for create, open, and close 


same as 1, also prints file format and size 
same as 2, also reports scanline r/w problems 


img_debug is initialized to 0. All messages are printed using the mi_debug printing routine. The 
library contains sanity checks that prevent operations on invalid miImg_file structs that have 
not been opened, or have been opened twice. 


The mi_img-_err_msg function prints an error message for the argument miImg_file structure, if 
an error occurred. The error is printed using mzi_error. 


5-3-10 Library Loader (LINK) 


This is the module of raylib that provides dynamic linking and runtime lookup of program 
symbols (e.g. names of shader functions). The LINK module provides the platform dependent 
facilities to compile source files to objects, to generate runtime loadable modules (aka shared 
libraries) from objects and to load and unload modules as needed by other raylib modules. It 
keeps a symbol table of all symbols in all libraries that were loaded, and allows lookups when, 
for example, a shader must be called by name. 


void mi_link_config( 


char *]_cmd, 
char *]1_options, 
char *C_cmd, 
char *]1_pathi, 
char *]_path2, 
char *1_path3) 


The LINK module depends on the systems compiler and linker. The location and calling 
convention may vary for every installation. This function overrides the built-in defaults with 
the custom linker command /_cmd, linker options /_options, compiler command c_cmd, and three 
library search paths /_path1,1_path2, and 1path3.The library search paths are simply concatenated; 
supporting three different arguments is a convenience for the caller because there are three defaults 
(user, environment, and built-in). Each of the argument paths may be a null pointer, in which 
case the corresponding default is not overridden. 
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void mi_link_ set_module_handle( 
void *mod) 


This function is available and necessary only on Windows NT. It lets the client application specity 
the module handle that should be passed to shader.1ib. The problem is that raylib might be 
linked into a client DLL that is linked into the client executable, so NT’s GetModuleHandle 
function would return a handle of the client executable but the shader interface functions are 
in the client library, which contains raylib. This would crash shader.1ib. The basic problem 
is that Windows NT is very bad at finding symbols — it must either know the name of the 
executable (which may vary and so cannot be hardwired into the library), or must be told 
explicitly, which is what this function is for. If this function is never called, milink-module 
defaults to GetModuleHandle. The mod argument has type void *, which is the same as type 
HMODULE. 


void mi_link_register_builtin( 
const char *fname, 
const miFunction_ptr func) 


Builtin functions that are to be called via the same interface as runtime loaded modules need to be 
registered with the LINK module. This function allows a pointer to a function func to be entered 
into the symbol table under the name fname, so that it can be retrieved with mi_link_lookup. This 
can be used to pre-register hardcoded shaders, for example. Symbols in libraries loaded with mz- 
link_file_add need not to be registered in this way, as this is done when they are first looked up 
(or at load time if the operating system does not support dynamic symbol lookup). 


miFunction_ptr mi_link_lookup( 
const char *kname ) 


This function looks up a function by name name in the symbol table, and returns a pointer to 
it. If zame cannot be found, a null pointer is returned. All currently loaded libraries (loaded 
with mi_link_file_add) and the list of pre-registered built-ins (from mi_link_register_builtin) are 
searched. The external libraries are looked up before built-in functions are searched thus allowing 
a replacement of a built-in function with a loaded library. If multiple libraries define the same 
symbol, it is undefined (and operating-system dependent) which is returned. 


typedef struct lmodule { 


int refcount; /* # of users of library */ 
int module_id; /* module id */ 

miBoolean libgenerated; /* generated from x.o */ 
miBoolean srcgenerated; /* generated from inline */ 
miBoolean coremodule; /* is a raylib coremodule */ 
miBoolean delayed; /* entered as delayed */ 
miLink_origin origin; /* module type */ 


char libfile [miPATHSIZE] ; /* locally loaded library */ 
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char rawfile[miPATHSIZE] ; /* unsubst. src/objfile */ 
void *libhandle; /* OS handle for library */ 
void *closehandle; /* NT auto close‘n’delete */ 
struct lmodule *next; /* next module */ 


} miLinkModule; 


void mi_link_info( 
miLinkModule ** 1m) 


Returns the head of a chain of miLinkModule records, linked with a next field. Each record 
describes a single linked library. If a library was linked multiple times, refcount is greater than 
1; it must be unlinked with mz_link_file_-remove that many times, passing the rawfile string. The 
libfile string is the file name after path substitution. The other fields are of little interest to the 
caller. The records should not be written to. 


void mi_link file _add( 


const char *file, /* name of a .c, .o or .so file */ 
miBoolean source, /* .c instead of .o/.so? */ 

miBoolean verbatin, /* came from $code .. $end code */ 
miBoolean delaylink); /* delay linking until mi_link_delayed */ 


Load a source file, object file, or library. For the given file, the parameter source determines 
whether it is to be loaded as a source or binary file. Binary modules can be plain object files 
(HP/UX needs relocatable objects that are compiled with the +z option) or directly loadable 
modules (shared libraries, DSO or DLL). If source is miFALSE, the extension of file is checked to 
determine whether the file is an object file (extension .o on Unix or .obj on Windows NT) or a 
shared library (.so on Unix or .d11 on Windows NT). If libraries are loaded more than once, a 
reference count ensures that it is loaded only the first time. 


The verbatim argument must be set to miTRUE if the given file is a source file that was generated 
from within raylib and is to be deleted on shutdown. Such source files are typically read from 
the scene file into a temporary file, which must be deleted when it is no longer needed. 


The delaylink parameter must be set to miTRUE if this function is called very early during 
initialization of raylib, at a point where the number of CPUs and the networking configuration 
is not yet known. This is commonly the case if libraries are loaded from the command line. It is 
recommended to avoid this case, and to always pass miFALSE. 


void mi_link file _remove( 
const char *file) 


Remove the previously loaded source, object, or library file file. A reference count keeps track of 
the number of additions and removals of a module. The module is only removed from memory 
(and disk if appropriate) if no reference to the module is left. The identity of a module is checked 
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only by a textual comparison of the given file name string. Do not delete a module that is still 
running, or mental ray will crash. 


Both mi_tlink_file.add and mi_link_fileremove only work on the master host in a networked 
environment. Slave hosts ignore them. 


5.3.11 Library (LIB) 


5.3.11.1. Introduction 


The library is a collection of general utility functions, implementing initialization and shutdown, 
error messages, and other low-level operations. Some functions of the library may in fact be 
implemented as macros; this is transparent to the caller. If macros are used, they are not capitalized. 


5.3.11.2 Initialization and Shutdown 


void mi_ntlib_init (void) 


raylib is highly portable and available for a wide range of systems ranging from PCs to 
supercomputers. It avoids operating-system dependent features whenever possible and relies 
on industry standards supported across all platforms, such as Posix. However, the Windows NT 
implementation of Posix leaves much to be desired, so raylib includes a Posix support library that 
implements the missing or broken functions. This sub-library must be initialized with a call to 
mintlib_init, between mi_raylib_attach_process and mi_raylib_init. On non-NT systems it does 
nothing. 


miBoolean mi_raylib_init ( 
const miBoolean slave, 
const int maxthreads, 
const miBoolean core) 


This function initializes all modules in the library in the proper order, except MEM and NTLIB 
(because services from these two modules are often required before a full library initialization). 
The functions called before mi_raylib_init are normally mi_raylib_attach process, mi_mem_error- 
handler, mi_img_error_handler, mi_mem_init, and mi_ntlib_init. 


If raylib is used as a DLL under Windows NT, mi_raylib_init should not be called from the 


DilMain because the startup of rendering threads would cause recursive calls of Di/Main. 


This function did not return a value until mental ray 3.3, where the return type was changed 
from void to miBoolean. If mental ray fails to start up, miFALSE is returned instead of exiting 
later. Common reason for such a failure are failures to start threads, or a failure to create local 
loopback network connections because an overzealous Windows firewall prohibits it. 
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void mi_raylib_exit (void) 


This function calls the exit functions of all modules in the proper order, more or less the reverse 
of what mi_raylib_init did. After this call no raylib function except mi_raylib_detach process may 
be used, not even mi_raylib_init. The only useful thing to do after exiting raylib is unloading it. 


miBoolean mi_raylib_attach_process (void) 


This function must be the very first raylib function to be called after the library is loaded. It 
allocates critical system resources needed even by all following raylib initialization functions. It 
returns miFALSE if unsuccessful. 


miBoolean mi_raylib_detach_process (void) 


This function does more or less the reverse of what mi_raylib_attach process did. It should be the 
very last raylib function to be called, right after mi_raylib_exit. 


Note that the initialization and the exit functions should all be called from one thread that stays 
alive during the entire lifetime of raylib. Other threads may later call raylib functions concurrently 
if they use the context functions described below. 


char *mi_raylib_date (void) 

Return a static string containing the date when raylib was created. 
char *mi_raylib_version(void) 

Return a static string containing the version number of raylib. 
void mi_version (void) 


Print two messages using mi_info containing the date, version, and architecture of raylib. Also 
prints one message for each raylibmodule using mzi_debug. 


typedef enum {miRL_VALUE, miRL_VALUE_EXEC, miRL_LINK, miRL_CODE, 
miRL_MI, miRL_SPDL, miRL_ECHO, miRL_SYSTEM } miRl_mode; 


char *mi_lib_registry_lookup ( 
char *xname , /* name of registry entry */ 
miRl_mode mode) ; /* what to look up, side effects */ 
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Look up a registry entry and return the string associated with the value of the key name. If there 
is no such key, or if no registry entry is found, return a null pointer. If side effects are enabled with 
mode miRL_VALUE_EXEC, also evaluate all the other keys the registry entry has, if found, in order. 
Mode miRL_value returns the standard value of the registry key; the other modes return auxiliary 
registry keys. All {zame} substrings in the name are evaluated. As a bonus feature, {$var} is 
an environment variable, and mental ray 3.4 allows {$?var}, which returns 1 if the environment 
variable var exists and 0 otherwise. A leading ’-’ character suppresses errors for non-existence. 


mental ray 3.2 and earlier accepted a boolean argument instead of a mode enum. miFALSE was 
equivalent to miRL_VALUE, and miTRUE was equivalent to miRL_VALUE_EXEC. Other modes were 
unavailable. The enum values were chosen to be backwards compatible. 


5.3.11.3. Errors and Messages 


Errors are grouped by severity. There are six levels, each with its own printing routine. The 
parameters are the same as for printf. The message is printed in the form 


module host.thread level: message 


with the module name module, the host number Host if available, the thread number thread with 
a leading dot if available, the message type /evel (fatal, error, warning etc), and the message given 
in the function call. Host and thread numbers are not available before and during initialization 
of the PAR and MSG modules. Host 0 is the master host, thread 0 is the master thread. Network 
threads are printed as .net. 


Some of the following routines may be implemented as macros. 


void mi_set_verbosity( 
const int level) 


Set the verbosity level bitmap. This bitmap controls which of the message-printing functions 
listed below will print messages and which will be ignored. The following level flags are available: 


miERR_NONE Print no messages at all (null bitmap). 
miERR-DEFAULT | Print fatal, error, and warning messages. 
miERR_FATAL If set, print fatal messages. 
miERR_ERROR If set, print error messages. 


miERR_WARNING | If set, print warnings. 

miERR_INFO If set, print infos. 

miERR_PROGRESS | If set, print progress reports. 
miERR_DEBUG If set, print debug messages. 
miERR_VDEBUG If set, print verbose debug messages. 
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Note that this bitmap is not what users use in the mi scene file or on the mental ray command 
line, where a number between 0 and 7 is expected. To convert from a number n to a bitmap, use 
(i<<n)-1. 


int mi_get_verbosity (void) 
Return the current verbosity bitmap, as set by default or with mi_set_verbosity. 


void mi_set_subverbosity ( 
const miModule mod, 
const miUint bitmap) 


Set the message bitmap for the given module, or all modules if mod is miM_NULL. The bitmap is 
unrelated to the bitmap used by mi_set_verbosity. It can be retrieved by modules with mi_get_ 
subverbosity to decide which classes of messages to print. 


The lower 24 bits of bitmap are predefined and valid for all modules; the upper 8 bits are reserved 
for module-specific classes. The following classes are predefined: 


miMSG_NONE 
miMSG_DEF 


No messages. 

Default messages. The LIB modules initializes all bitmaps with this 
value on startup. 

All classes, including the reserved classes. 

Phase messages, such as “begin tessellation.” 

Progress messages, such as number of lines parsed or percentage of 


the job finished. 


miMSG_ALL 
miMSG_PHASE 
miMSG_PROGRESS 


miMSG_VPROGRESS 


miMSG_RUNTIME 
miMSG_SCENE 
miMSG_MEMORY 
miMSG_RENDER 
miMSG_VRENDER 


miMSG_RESOURCES 


miMSG_NETWORK 
miMSG_FILES 


miMSG_DEBUG 


Verbose progress messages, such as per-task percentages of the job 
finished. 

Wallclock and CPU user time reports. 

Scene statistics, such as the number of triangles or BSP tree statistics. 
Memory usage statistics. 

Standard rendering statistics, such as the number of rays cast. 
Verbose rendering statistics, such as shader call counts or cache 
statistics. 

Internal resource usage, such as number of task queues and tasks 
used, message passing statistics, or DB access statistics. 

Low-level networking statistics. 

File read/write statistics, reports all files being accessed and any path 
substitutions performed. 

Generic debugging messages. This class and the following can be 
used for modules that only support one or two types of debug 
messages. This avoids the need to define module-specific classes. 


686 5 Integration of mental ray 


void mi_get_subverbosity ( 
const miModule mod) 


Retrieve the message bitmap for the given module. This is used by modules to find out which 
messages to print. 


void mi_errorhandler ( 
void (*const handler) (const int errmask, 
const char *const fullmsg, 
const char *const rawmsg, 
const int code) ) 


If a message of any class (fatal, error, warning, info, progress, debug, or vdebug) is printed, call 
the named function with four parameters: the error level bitmap with exactly one of the miERR- 
* bits set; the full message with module, host, thread, and level information; the raw message 
without this information, and a code number that identifies the error or warning. No newline 
is appended to either message. This handler routine is called only for levels allowed by mi-_set- 
verbosity (default is fatals, errors, and warnings). The default printing routine prints the full 
message to stderr, followed by a newline. 


The code number consists of six decimal digits: two for the module number (one of miM_*), one 
for the severity level (0 for fatal, 1 for error, 2 for warning), and three that are either 0 or uniquely 
identify the error or warning message. The last three digits are 0 for messages that have not yet 
been assigned an unique error code, such as messages printed by shaders. The last three digits 
are shared by fatal and error messages (no two have the same), but a warning may use the same 
trailing three-digit code as either an error or a fatal. The code number is the number that is printed 
to stderr. Once assigned, mental images will avoid changing code numbers, but if a message is 
dropped from raylib its number will be recycled for future new messages. 


This function can be used to print messages into an application error log, or pop up dialog boxes 
etc. It is also the only way to catch fatal errors, which normally exit immediately. However, 
before exiting they call the error handler, which then has the chance to longjmp to a safe place 
and unload the raylib library to protect the application. 


void mi. fatal ( 
const char *const message, ...) 


An unrecoverable error has occurred. Unlike all others, this call will not return. The messages 
printed by this and the following six functions may be suppressed with appropriate mi_set- 
verbosity calls. 


void mi_error(const char *const message, ...) 


An unrecoverable error has occurred. This call returns; the caller should abort the current 
operation gracefully and return. 
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void mi_warning( 
const char *const message, ...) 


A recoverable error occurred. The current operation proceeds. 


void mi_info( 
const char *const message, ...) 


Prints information about the current operation, such as the number of triangles and timing 
information. Infos should be used sparingly; don’t print information for every object or surface 
tessellated. 


void mi_progress ( 
const char *const message, ...) 


Prints progress reports, such as rendering percentages. 


void mi_debug( 
const char *const message, ...) 


Prints debugging information useful only for mental images. This level might be unavailable in 
production versions. 


void mi_vdebug ( 
const char *const message, ...) 


Prints more debugging information useful only for implementors. Messages that are likely to be 
useful only in rare circumstances, or that generate a very large number of lines should be printed 
with mi_vdebug. 


void mi_set_colormessage ( 
const miBoolean) 


If the color message mode is set to miTRUE, then messages are prefixed and postfixed with ISO 
color escape sequences on Unix platforms. For Windows NT, if message output is to the console 
then the console color is changed programmatically. The following messages are affected: fatal, 
error, warning, debug and vdebug. The color assignment is fixed and cannot be changed. The 
color messages are disabled by default. The message string passed to the message callback does 
not contain color escape sequences. 
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void mi_lib_message_flush (void) 


?-l Messages are sometimes delayed to prevent messages from multiple threads or hosts to run 
into each other. This is done by collecting them into a queue that is periodically flushed. This call 
flushes the queue immediately by printing all pending messages. It should be used only in the 
master thread of the master host (that is, from the application, not from a shader). mental ray 3.x 
no longer blocks messages and does not require this function. 


5.3.11.4 Context Support 


This section applies to mental ray 2.1 only. mental ray 3.x can tell threads apart, and automatically 
create contexts, without explicit context function calls from the application. 


raylib can handle multiple contexts a time. A context represents all information raylib needs to 
hold a certain state between calls of raylib -functions. For example, API functions often consist of 
a pair of functions (such as mi_api_object_begin and mi_api_object_end) that begin and complete 
a certain transaction. If two threads were to use these functions simultaneously, they would 
become confused — raylib would essentially see two begins and two ends, and would not be 
able to distinguish them. The begin call sets some internal information in local variables called a 
context that the end call needs to complete the transaction. A second begin call would overwrite 
the context and would confuse both transactions. 


For this reason raylib supports multiple sets of contexts. Two threads can safely execute begin/end 
pairs concurrently as long as they do it in different contexts. Contexts can be created, attached, 
detached, and destroyed. Typically, but not necessarily, every application thread that needs to 
deal with the raylib API without stepping on the toes of other threads that do the same, should 
create and attach its own context. 


Contexts are tightly coupled to threads. Whenever the current context is changed this change 
applies to the thread that issues the request. The thread stays in that context until it changes to 
another one. All operations carried out by the thread have potential affect to the state the context 
represents. The context information is carried by thread local storage that is accessible by every 
raylib -function thus avoiding the need to pass this information explicitly. 


A thread that has never called raylib since its creation should call mi_context_attach first. It is then 
recognized and given the appropriate context. This does not apply to the thread that initialized 
raylib. This originator thread should stay alive during the lifetime of raylib and perform the exit 
operations at the end of the usage. It always operates in “context zero” that is created by raylib 
automatically during initialization. 


Only one thread can attach a certain context at any time (except the default context), and one 
thread can only attach a single context at a time. Two threads that are attached to different contexts 
may call raylib functions concurrently and either operate on a distinct set of context informations 
or block each other to avoid concurrent access to shared data. The interface to shaders contains 
no support for contexts. Therefore operations which involve calling of shaders do not allow 
concurrent operations of different threads. 
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Some raylib resources are not thread-dependent but shared among all contexts. The scene database 
and the LINK symbol table are of this type and need proper coordination by the application 
to avoid conflicts. For example, a symbol put into the symbol table, or an element put into the 
database, immediately become visible to all threads. Access to all these functions is thread-safe 
and does not require application locking. 


Support for handling contexts is given by the following functions: 
miContext mi_context_create (void) 


2.1 This function creates a new context. The ID of the context is returned. The context is not yet 
attached to any thread. 


void mi_context_remove ( 
miContext ctx) 


?-! This function removes an existing context. It is not allowed to remove a context that is attached 
to any thread or to remove the default context. 


miBoolean mi_context_attach( 
miContext ctx) 


2-1 This call attaches the context ctx to the calling thread. If the thread was attached to another 
context, the thread is detached from that context. Attaching to the default context (miCONTEXT_ 
DFLT) effectively detaches from any other context. If the function returns miFALSE the context 
could not be attached and the calling thread stays attached to its current context. The call fails, 
if the context ID is illegal, if the context is already attached to another thread (even if it is 
the calling thread) or if the current context cannot be determined. The default context can be 
attached by more than one thread which then should not call any context dependent function 
concurrently. The termination of a thread does not automatically detach it from the current 
context. To avoid unaccessible contexts a thread should call m1_context_attach (miCONTEXT_DFLT) 
before termination if it has attached another context previously. 


void mi_context_render_context (void) 


2-1 Applies the context of the calling thread to the render threads for operations that use thread 
parallelism. Render threads are threads started internally by raylib to permit multithreaded 
tessellation and rendering. One render thread is the one from which the tessellation or rendering 
operation is started using a call like mi_rc_run; maxthreads — 1 more are started if the call to mi_ 
raylib_init specified maxthreads render threads. These extra render threads they are not visible 
to application threads. However, it is important that all render threads, the one that executes 
mi_par_run and the maxthreads — 1 others, all run in the same context. The mi_context_render- 
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context function attaches the extra maxthreads — 1 threads to the same context as the calling 
thread, which can then safely call mi_par_run. It is recommended that mi_par-_run is called from 
the default context, in which case no call to mi_context_render-_context is necessary. 


miContext mi_context_get (void) 


*-! Returns the current context ID of the calling thread. 
5.3.11.5 Licensing 


The raylib requires licenses to run. These functions take care of licenses: 


int mi_raylib_license_get ( 
Bhs nthreads) 


This function requests and checks out licenses for nthreads threads. It returns the number of 
threads that are allowed to run, which may be less than or at most equal to nthreads. If zero is 
returned, the library cannot run. The returned number must later be passed to mi_raylib_init. It 
mi_raylib_init is called with a number of threads other than the number returned by mi_raylib_ 
license_get, the library will not work correctly! 


This call applies only to the “master” mental ray. If there are server hosts that participate in 
rendering, they will obtain their own licenses. 


void mi_raylib_license_release (void) 


This function releases all licenses previously checked out with mi_raylib_license_get. It should be 
called just before mi_raylib_exit to make the licenses available to other programs. 


5-3-12 Parallelism and Networking 


There are two types of parallelism built into raylib: thread parallelism on shared-memory systems, 
and network parallelism. Raylib attempts to run one process or thread (optionally, if available) 
on each CPU on the network. On multiprocessor shared-memory systems, the scene database 
is stored in shared memory and can be accessed by all rendering processes. Network parallelism 
cannot share data this way; it requires multiple copies of the database in each host’s local memory. 
The DB module handles all network transfers of database items. All network transfers rely on 
message passing. 
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5.3.12.1 Host Selection 


void mi_msg_add_host ( 
const char *xhostname, 
const int socket_id) 


Nominates a host for network rendering. This must be called after mi_raylib_process_attach and 
before mi_raylib_init. The hostname argument is expected to be the name of a machine that 
offers a mental ray service. Optionally, a colon followed by a port number may be appended. 
The service name is taken from the environment variables MI_-RAY3_SERVICE (mental ray 3.0 or 
later), MI-RAY2_SERVICE (mental ray 2.0 or later), or MI-RAY_SERVICE, if defined, and default to 
mi-ray3/tcp (mental ray 3.0 or later), mi-ray2/tcp (mental ray 2.0 or later), or mi-ray/tcp. 
The service name is then looked up in the operating system’s services database if available to 
obtain the IP port number; if this fails it defaults to 7002. The server host will be contacted 
during initialization, and if it passes the negotiation phase it will be available for tessellation and 
rendering as a mental ray server. See the installation guide for installing a machine as a mental 
ray server. The socketzd argument should always be set to -1. Note that mi_msg_add_host does 
not immediately connect to the host but builds a list of hosts that will be connected during m1_ 
raylib_init. 


Note that standalone mental ray executables use this function for every host found in the 
.ray3hosts (mental ray 3.0 or later), .ray2hosts (mental ray 2.0 or later), or .rayhosts file in 
the current or home directory, except for the first line that matches the host name. If the host is 
called castor, the first line in the file referencing castor (but not aliases such as localhost) is ignored 
and not passed to mi_msg_add_host. This is done to allow sharing a host list between all hosts. 


void mi_msg_remove_host ( 
const char *hostname) 


°-'Remove a slave host from the host list. The host will not be given any new jobs from this point 
on, and when it has finished its current jobs it will be disconnected. This means that there may 
be some delay before the host is disconnected. 


const char *mi_msg_no_of_cpus (void) 


Return the number of processors on the local host. This call can be used before mi_raylib_init to 
determine a good number of render threads to use (passed as second argument of mi_raylib_init). 


5.3-12.2 Recoverable Aborts 


When raylib is performing complex operations (mainly tessellating geometry or rendering the 
scene from within mi_par_run) it can be aborted. Aborting means that the current function 
returns as fast as possible without completing the task. This may leave objects untessellated, 
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pixels unrendered, and so on, but unlike a call to mi_fatal all data remains in a clean state so the 
operation can be done again later. This is intended for “Cancel” or “Abort” buttons in the user 
interface of applications that raylib is built into. 


void mi_par_abort ( 
int bitmap) 


Clear or set the current abort status. If bitmap is 0, clear all abort status; this should be done when 
an operation has completed aborting and returned to the application that has caused the abort. If 
bitmap is a small integer, bitwise-OR it to the system abort bitmap; otherwise bitwise-AND it 
with the system abort bitmap. This can be used to set and clear individual bits. For example, the 
user abort is set with 1 and cleared with ~ 1. There are four defined bits in the bitmap: 


O Application abort (user pressed an abort button). This is the only bit that should be used 
by raylib client applications (and only raylib clients, it should not be used by raylib itself). 


1 Intra-raylib aborts that tells all threads that all tasks are finished and they can stop now. 
This is necessary because near the end threads will dequeue in-progress tasks, and as soon 
as the last in-progress task is finished the threads that are also working on the same task 
need to be killed without doing an application abort, which may be pending and may not 
be reset. 


2 ‘~All threads are shutting down 
3 Caught a fatal signal, shutting down 


The new system abort bitmap is broadcast to all connected hosts. If any bits in the system abort 
map have been set, mi_par_aborted will from then on return nonzero. When the abort is complete 
and execution returns to the mainline after all threads have terminated, mi_par_abort must be 
called to clear the relevant bits. 


int mi_par_aborted (void) 


Every function that uses a large amount of time must periodically call mi_par_aborted and clean 
up and return if it returns miTRUE. Cleaning up includes releasing memory, locks, and other static 
information to return them to a state where the operation can be retried later. For example, a 
long-running output shader might use this call once for every scanline it completes, and break 
out of the scanline loop if nonzero is returned. 


void mi_par_register_abortcallback( 
miBoolean (*callback) (void) ) 


This function registers a callback function that will be called by raylib whenever mi_par_aborted 
is called. The callback function may return miTRUE to abort raylib, as if mi_par_abort had been 
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called. The number of calls to callback is limited to one per second for performance reasons. 
The purpose of the callback is to allow non-multithreaded applications that raylib is built into 
to periodically check whether the user has pressed a “Cancel” or “Abort” button. Multithreaded 
applications should use mi_par_abort from another thread instead of the abort callback because 
there is a small performance penalty involved in polling abort buttons. 


miBoolean mi_job_set_slaves_active( 
miBoolean on) 


°° Enable or disable slave host participation. Sometimes previews are faster without network 
rendering due to the network transmission latencies. This function allows to disable slaves 
temporarily. 


Chapter 6 


Upgrading 


6.1 Upgrading from mental ray 3.0 to 3.1 


mental ray 3.1 is a new major version of mental ray and has a very similar interface. Very little 
upgrading work is necessary, but there are a number of additional features. 


6.1.1 Rendering Algorithms 


e A new hierarchical grid acceleration algorithm was introduced that allows much better 
control than the old static grid accelerator in mental ray 2.1. 


e Multipass rendering and merging is now supported. Render passes are independent renders 
of portions of the same scene, each generating a subsample-based layer file. Layer files can be 
merged back when rendering the last pass, or all layers can be merged as a separate process. 
Merging can be done in custom merging functions. Multipass rendering was introduced in 
mental ray 3.1.1, and was significantly enhanced (using an incompatible syntax extension) 
in mental ray 3.1.2. 


e The -nomaster command-line option and the mi_job_set_slaves_only function call allow 
excluding the master from all tasks that can be handled on slaves, such as rendering and 
tessellating. 


e The bsp shadow on option enables the new shadow BSP tree, which holds all shadow 
objects. The main BSP tree then only holds trace objects. This is useful if the scene contains 
simplified shadow stand-in geometry and has very low shadow ray coherence, for example 
if a light dome computed from a chrome dome photograph is used. 


e The new multipass rendering facilities allow rendering a scene in passes, and combining the 
results on a subpixel level. 


e Objects may specify min and max sampling parameters that constrain the sampling range in 
the options. For eye rays that do not see any objects, the samples statement in the options 
block allows an optional default constraint. 
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6.1.2 Scene Description Language 


e Multiple motion vectors are now possible, and may require changes to shaders that evaluate 
motion vectors. (Normally mental ray handles motion vectors internally but post-motion 
output shaders might exist that access them directly.) 


e A polygon vertex or free-form surface control point may have up to 15 motion vectors 
instead of only one. Multiple motion vectors define a path to allow curved motion blur. 
For motion transformations, a new motion steps option specifies the number of curve 
points to generate. 


e Shutter statements may optionally define two values, a new shutter delay value defines the 
shutter open time in addition to the standard shutter close time. 


e Two new types of area light source was introduced: one that uses any geometric object to 
define the shape of the light; and a user type that lets the light shader pick points on the 
light surface, and control integration in the material shader with state — count. 


e A new hair geometry primitive was introduced that can efficiently render large numbers of 
hairs. Hairs are assumed to be small in screen space, in the range of one pixel wide or less. 


e The new fine approximation mode allows efficient tessellation of freeform surfaces and 
displacement to microtriangles, which allows extremely detailed displacement without the 
previous high memory demands. This works with all rendering modes, including shadows 
and self-shadowing, motion blurring, ray tracing, global illumination, etc. See page 166 for 
details. 


e The new sharp approximation feature controls the sharpness of tessellations, by controlling 
the facet normals. 


e New command-line options: -approx, -approx_displace, -bsp_shadow, -diagnostic 
finalgather, -grid_depth, -grid_resolution, -grid_size, -nomaster, -motion-_ 
steps, -samples with four arguments. 


e New options block statements: bsp shadow, diagnostic finalgather, grid depth, 
grid resolution, grid size, motion steps, pass, samples with four arguments, 
shutter with delay argument, traversal. Image type "rgbe" in camera output statements, 
pass chain in the camera, lightprofile shader parameter type, apply photonvol in 
declarations, light profile blocks lightprofile...end lightprofile, fine and sharp 
attributes in approximations, and the writable attribute for texture statements. mental 
ray can use writable textures directly for rendering; mental ray 3.0 required a separate 
non-writable texture statement referencing the same file name. 


e New image data types for RGBE (8-bit high dynamic range color data), and floating-point 
alpha and intensity channels including no-elliptic pyramid filtering for one-channel images. 
New image file formats IFF (Alias Maya), Radiance HDR, and HT (simple uncompressed 
HDR image). 


e Inheritance functions are deprecated (but still supported), and replaced with the more 
powerful traversal functions that have full control over all forms of inheritance, including 
flags and materials. 
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6.1.3. Shader Writing and Integration 


e Shaders can now define thread local shader storage, to replace the simple method of indexing 
an array with a thread number, which worked in mental ray 2.1 but not 3.x. See page 408 
for details. 


e The mi_trace_probe shader interface function in mental ray 3.1 finds objects with any flags, 
including visible and shadow; mental ray 3.2 will probe only objects marked trace. The 
state type is miTRACE_PROBE. 


e High Dynamic Range images allow more compact storage of RGB color values greater 
than 1.0. 


e IES and Eulumdat light profiles are supported. There is a new lightprofile ... 
lightprofile end block, and a new lightprofile shader parameter type. Light profile 
data can be passed to shaders in a similar way to user data. New mi_query modes, m1- 
api_lightprofile.* geometry shader API functions, and mi_lightprofile_* shader interface 


functions were introduced. 
e Image streaming, which is part of the mental ray integration interface, has changed. 


e Slave hosts can be added and removed at any time between frames, instead of using a list 
fixed at startup time, using the mi_msg_add_host and mi_msg_remove_host. 


e New modes for mi_query were added: 
miQ_FUNC_TLS_GET 
miQ_FUNC_TLS_GETALL 
miQ_FUNC_TLS_SET 
miQ_-LIGHTPROFILE_COSTHETA_MAX 
miQ_-LIGHTPROFILE_COSTHETA_MIN 
miQ_LIGHTPROFILE_INTENSITY_MAX 
miQ_-LIGHTPROFILE_PHI_MAX 
miQ_LIGHTPROFILE_PHI_MIN 
miQ_-LIGHTPROFILE_PHI_RES 
miQ_LIGHTPROFILE_THETA_RES 
miQ_LIGHT_CAUSTIC_PHOTONS_EMIT 
miQ_LIGHT_GLOBAL_PHOTONS_EMIT 


e Here is the complete list of new shader and integration interface functions: 
mi_apihair_begin 
mi_apihair_end 
miapi_hairhairs_add 
mi_apt_hair_hairs_begin 
mi_api_hair_hairs_end 
mi_api_hair_info 
mi_api_hair_scalars_begin 
mi_api_hair_scalars_end 
mi_tlightprofile_sample 
mi_lightprofile_value 


mi_msg_remove_host 
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6.2 
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mi_renderpass_access 
mi_volume_instances 


Upgrading from mental ray 3.1 to 3.2 


mental ray 3.2 is a fully backwards-compatible feature upgrade of mental ray 3.1. 


6.2.1 


Rendering Algorithms 


Added Rapid Motion rendering algorithm, now renamed to the rasterizer, that performs 
efficient motion blurring by shading geometry at a single point in time, and caching and 
re-using the results at multiple points that the object moves across. It is enabled with the 
scanline rapid statement in the options, or the -scanline rapid command-line option. 
A new samples collect option statement controls second-stage sample compositing. 


Implemented scene data swapping to disk, effectively extending available memory by a 
region on disk. It is enabled and set up with the -swap_dir and -swap_limit command- 
line arguments. 


The state — motion state variable is now interpolated from explicit motion vectors (but 
not motion transformations) if motion blurring is turned off. 


Shadowmap files now contain extra information at the end of the regular depth data that 
defines a coordinate system for reloading the shadow map into a different scene. 


6.2.2 Scene Description Language 


Subdivision surface rendering is supported without a separate mental matter library. 
(Subdivision surface modeling still requires mental matter.) 


Added shadowmap rebuild merge to light sources to read and add to existing shadowmap 


files. 


Added a max displace and -maxdisplace override option, useful for using mental ray 
3.2 with older translators that do not generate maximum displacement distances. 


Added a -texture_continue command-line option that makes mental ray continue if a 
texture file cannot be found, instead of aborting immediately. 


Support for limited forward referencing of instances, objects, objects, lights, and cameras. 


Objects that are only visible but not traced are no longer visible to rays and photons. This 
is an issue for final gathering and all mz_trace_* shader interface functions, in particular m1_ 
trace probe. 
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e The maximum length of mental ray tokens was increased to 4095 characters, and message 
length limits are increased as well. 


e Camera output statements now accept the new image format png (Portable Network 
Graphics), and Alias Maya IFF files accept "+rgba,z" as a data type string. 


e New statements in the options block: 
scanline rapid 
samples collect N 
Shadowmap only 
finalgather rebuild freeze 
finalgather falloff N 
finalgather depth NNN 
finalgather filter N 
displace presample on|off 
acceleration large bsp 
motion on|off 
max displace N 
filter clip lanczos 
filter clip mitchell 
photon autovolume on|off 

New statements in objects and instances: 

visible trace shadow globillum caustics approximate 
approximate regular parametric N% Nz 


approximate ... sharp WN (with a floating-point N) 
New statements in instances: 
override ... approximate 


New statements in light sources: 
Shadowmap rebuild merge 

New statements in cameras: 
pass "typelist" 

New commands: 
touch E 


e New command-line options: -scanline rapid 
-samples_collect N 
-shadowmap_only 
-finalgather_rebuild freeze 
-finalgather_ falloff N 
-finalgather_depth NNN 
-finalgather filter N 
-swap_dir § 
-swap_limit N 
-texture_continue 
-memory N (-jobmemory is obsolete and removed) 
-displace_presample on|off 
-acceleration largebsp 
-echo incremental 
-motion onloff 
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-maxdisplace N 


6.2.3. Shader Writing and Integration 


e Shader color and scalar results can be checked for illegal not-a-number (NaN, for example 
the square root of a negative number) results with -message phen debug --. NaNs 
typically cause unexpected black or white pixels. 


e New modes for mi_query were added: 
miQ_FINALGATHER_STATE 
miQ_FUNC_TAG 
miQ_FUNC_CALLTYPE 
miQ_PIXEL_SAMPLE 


e Here is the complete list of new shader and integration interface functions: 
m1_opacity-_set 
m1_opacity_get 
mi_shaderstate_set 
mi_shaderstate_get 
mi_shaderstate_enumerate 
mi_finalgather-_store 
mi_ray falloff 
mi_ray-offset 


mi_raster_unit 
mimem_memory-_limit 
mijob_memory_limit is obsolete and was removed. 


e A number of bitmap arguments of type miUlong were changed to miUint, because miUlong 
is now a 64-bit integer on 64-bit platforms. 


e The shader state variable dot_nd is now computed even if the light is rejected because there 
is no surface, like in a volume shader. 


e The cnst array in the mzApprox data structure was changed from doubles to floats to make 
room for more options. This requires a recompilation of geometry shaders that access these 


fields (which is rather unlikely). 


e The callback installed by the mi_disp_stream_cb_begin integration function receives full 
frame buffers instead of small rectangle-sized image scraps. The lower left pixel of each 
received rectangle is now at (x/, y/) instead of (0, 0) in the image tag provided to the callback. 
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6.3 


6.3.1 


Upgrading from mental ray 3.2 to 3.3 


Rendering Algorithms 


Introduced detail shadowmaps that can multisample shadowmap pixels, and also call 
shadow shaders on shadow-casting geometry to obtain and store transparent shadows. 


Shadowmaps can now specify a shadowmap bias to replace the standard Woo trick, which 
stores the halfway distance between the first two shadow-casting objects, with a fixed 
distance. The bias can also be set in the options. Although Woo shadowmaps are generally 
superior, they are not compatible with shadowmap merging, which was also added to 
mental ray 3.3 to support shadows cast from one rendering pass on another. Note that 
mental ray 3.3 will read shadowmap files created with older versions of mental ray, but 
older versions cannot read the new 3.3 format. 


Shadowmaps also support extra fields supplied by a camera attached to the light source. 


Uncompressed HDR (High Dynamic Range) images are now supported in addition to 
compressed HDR images. 


Performance improvements: Light emitter shaders now work several times faster. 
Raytracing motion-blurred hair geometry, and hair rendering in general, is also several 
times faster. Significantly improved final gathering performance for surfaces with very 
strong bump mapping; for extreme bump mapping, performance can increase by a factor of 
10. Scenes with very large numbers of instances are rendered much faster with far reduced 
memory overhead. Frame buffers now take about half as much space. 


Large finely displaced objects of which only a very small part is in the viewing frustum, 
and the bulk of the object to the side or behind the camera, are now handled much more 
efficiently. Much less subdivision effort is expended on invisible portions of such objects. 


For hyperthreaded Intel CPUs and Linux, the -threads command-line option now 
includes hyperthreaded pseudo CPUs. These pseudo-CPUs will not consume licenses. 


Autovolume mode no longer requires ray tracing. 


Multihosted rendering could get wedged in mental ray 3.2 under certain circumstances. 
mental ray 3.3 has a new networking algorithm that is completely stable, and also much 
faster, permitting more slave hosts to contribute efficiently. 


The multipass rendering file format was changed. Old files can be imported, but older 
versions of mental ray cannot read the new format. 


mental ray is now much more frugal with stack allocations. The default stack size was 
reduced from 4 MB to 512 KB. This reduces memory requirements and the risk of being 
unable to start another thread. If 512 KB is insufficient, it can be overridden with the MI_ 
STACKSIZE environment variable. 
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6.3.2. Scene Description Language 


Detail shadowmaps introduce several new statements to light blocks: shadowmap detail, 
shadowmap detail samples, shadowmap accuracy, shadowmap color, and shadowmap 
alpha. Also, shadowmap bias was added for biased, non-Woo shadowmaps. 


ILM’s OpenEXR 1.1 image file format is now supported. It is installed as an external library 
that is part of the mental ray distribution. The BW/A variant of Alias IFF image files is 
now supported. RGBE frame buffers are no longer gamma-corrected. 


Double-quoted strings may now contain the sequence 
", which denotes a literal double quote. This makes it possible to put literal double quotes 
inside strings, which can be useful for system commands. 


Added conditionals to the language, such as $ifdef and $ifeq. 


Added an offscreen flag to approximations to disable coarse tessellations outside the 
viewing frustum. 


Added a touch statement to mark objects for re-evaluation. 
It is now possible to attach multiple finalgather file names to the options block. 


Shader parameters of type ight now accept instances of light groups, in addition to instances 
of lights. The light group contains instances of lights that will be treated as if they were a 
single light. 


Added namespace support, using namespace ... end namespace brackets. Elements inside 
a namespace N can be referenced by prefixing their name with N: :. Inside a namespace, a 
global symbol S can be referenced as : :S. 


Hair geometry can now be rendered in rasterizer (formerly called Rapid Motion) mode. 


Numerical non-array shader parameters may be declared with defaults using a default 
keyword in the declaration block. 


The hard max limit of 7 for approximation subdivision has been removed for displacement 
approximations. 


Materials can omit the material shader, and objects and instances may specify the new flag 
shadowmap off. Both are useful for hull objects that are not visible themselves but enclose 
volume effects such as visible light cones. 
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6.3.3. Shader Writing and Integration 


e The mi_compute_trradiance shader interface function, if called to evaluate irradiance from 
final gathering, will return the average of all alphas from finalgather rays. It was previously 
undefined. This allows a simple form of ambient occlusion mapping. 


e A new geometry shader interface function mi_api_parameter_default allows supplying 
default values for declared numerical shader parameters. 


e The mi_X_from_Y shader interface functions now work when called from displacement 
shaders. 


e The state — bary[0] coordinate for hair was changed to a range of (0, 1) from the left to 
the right edge of the hair, as seen from the camera. Previously it was defined in the range 
(1, 0, 1) with O at the center. 


e Added a mi_trace_continue shader interface function that continues the current ray with 
the same state and type, as if the intersection had not happened. 


e Added a mi_api_touch geometry shader interface function to mark objects for re-evaluation. 


e In rasterizer (formerly called Rapid Motion) mode, environment shaders now receive the 
raster_x and raster_y state variables. 


e The miQ_GEO_LABEL mode of the mi_query shader interface function may now be used from 
displacement shaders. 


e Multiple finalgather file names can be attached to options with mi_api_taglist_reset. 


e The callback installed by the mz_disp_stream_cb_begin integration function receives a pointer 
to a tag list, not a single tag. This allows access to all frame buffers, not just the main color 
frame buffer. Also, the tags pointed to are the full frame buffers, not the small image 
rectangles, so it is necessary to use the x/ and y/ arguments to offset into them. (This will 
change again in 3.4.) 


e The 128-byte stub files now specify version number 3.3, and add another port number at 
the end that can be used for bidirectional connections that allow a realtime viewer to request 
arbitrary frame bufters, in their native format without interleaved 8-bit RGBA conversion. 
The zmf_disp viewer does not support this new mode. 


e The second argument of the mi_lib_registry_lookup integration interface function now 
expects a miRL_* enum code instead of a miBoolean. The enum codes were chosen to 
be backwards compatible without recompilation. 


e The mi_raylib_init integration interface function now returns a boolean that indicates an 
initialization failure if miFALSE. Common reason for such a failure are failures to start 
threads, or a failure to create local loopback network connections because an overzealous 
Windows firewall prohibits it. 


e First derivatives on subdivision surface, free-form surface, and polygonal (if available) 
geometry are now made available to displacement shaders. Also, the result pointer passed to 
displacement shaders when displacing subdivision surfaces now points to cleared memory 
(this was already the case for other geometry types). 
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e At startup, mental ray will record the thread priority and use it for all render threads it 


creates later. This allows the application that mental ray is embedded in to reduce rendering 
priority to keep the GUI responsive. 


e The .rayhosts file lists the names of slave hosts to attach to for network rendering. It is now 


possible to append -threads 7 to each line to control the number of threads on that host. 
This used to work in version 2.x but not 3.x. 


Translators may specify triangle meshes as triangle lists, which directly correspond with 
renderable data structures without requiring tessellation. (The downside is that they change 
between major mental ray versions.) 


6.4 Upgrading from mental ray 3.3 to 3.4 


oe 


Rendering Algorithms 


Replaced the Rapid Motion algorithm with a new renderer called the rasterizer, which is 
an alternative to the regular scanline renderer. For backwards compatibility, the existing 
controlling options were mostly retained except as described below. 


Added color profiles. 


6.4.2 Scene Description Language 


The samples collect statement, which sets the number of samples filtered by the 
rasterizer, now defaults to 4 (16 samples) instead of defaulting to a number derived from 
the oversampling parameters. 


The shading samples statement sets the number of shading points per pixel taken by the 
rasterizer. 


The hardware samples statement controls the supersampling and multisampling settings 
of the hardware renderer. 


The finalgather trace depth statement has another parameter to control the diffuse 
trace depth. 


The lightmap and lightmap only statements control light mapping. 
The photonmap only statements controls photon mapping. 


The caustic scale, globillum scale, and finalgather scale statements supply a 
scaling factor to the brightness of these effects. 


The finalgather presample density statement adjusts the number of finalgather points 
during finalgather preprocessing, as a correction factor. 
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e The colorspace statements, and their references in output and texture statements, control 
the color space (sRGB, CIE, etc) used for rendering, loading, and saving images. 


e The compress modifier on output statements selects OpenEXR compression modes none, 
piz, Zip, rle, or pxr24. 


e The trace flag in instances and objects was replaced with separate reflection, 
refraction, transparency, and finalgather flags that follow the syntax of globillun. 
So does the shadow flag. 


e The shadowmap filter statement in a light definition controls shadowmap filtering. 


e A new variant of directional light can be specified by supplying both an origin and a 
direction, but not spread because that would turn the light into a spot light. A directional 
light with an origin does not illuminate points behind the plane defined by the origin and 
direction. 


e The volume group statement in an object ties together all objects with the same object 
group number such that autovolume mode treats them as belonging to the same object 
with a single inside volume. 


e The trilist toplevel element is an alternative to object definitions that allows very efficient 
definition of geometry consisting entirely of triangles. 


e The nosmoothing flag in approximations turns off normal interpolation during fine 
tessellation. 


e The contour and contour normal approximation modes were removed. 


e The new command-line option -fb_dir S specifies a directory where mental ray can save 
frame buffer files while rendering. Frame buffers can be very large, and mental ray 3.4 has 
no upper limit on the number of frame buffers, so they are no longer permanently stored 
in memory but can be paged out to disk. 


6.4.3. Shader Writing and Integration 


Since the miOptions data structure, and the methods for accessing frame buffers have changed, 
all shaders that use the geometry shader interface must at least be recompiled. All output shaders 
need to be modified and recompiled. 


e New modes for mi_query were added: 
miQ_INST_FINALGATHER 
miQ_OBJ_FINALGATHER 
miQ_TEXTURE_DIM 


e Here is the preliminary list of new shader and integration interface functions: 
mi_apt-_colorprofile_begin 
mi_apt_colorprofile_end 
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mi_apt_colorprofile_space 
mi_api_colorprofile_white 
mi_api_output_colorprofile 
mi_apiprimlist_ approx 
miapiprimlist_begin 
miapiprimlist_border 
mi_api_primlist_dimensions 
mi_apiprimlist_end 
mi_api_primlist_topology 
mi_call_contour_material 
mi_colorprofile_ciexyz_id 
mi_colorprofile_ciexyz_to_internal 
mi_colorprofile_ciexyz_to_render 
mi_colorprofile internal_to_ciexyz 
m1i_colorprofile_internal_to_render 
mi_colorprofile_internalspace_id 
mi_colorprofile_render_to_ciexyz 
mi_colorprofile_render_to_internal 
mi_colorprofile_renderspaceid 
mi_continue shadow-seg 
mi_disp_fbmap 

mi_disp_fbunmap 
mi_output_image-close 
mi_output_image-_open 
mi_reflection_dir_anisglossy_x 
mi_reflection_dir_diffuse_x 
mi_reflection_dir_glossy_x 
mi_texture interpolate 
mi_transmission_dir_anisglossy_x 
mi_transmission_dir_diffuse_x 
mi_transmission_dir_glossy_x 


The zmage pointer has been removed from the options. Output shaders must call m1_output- 
image_open and mi_output_image-close for frame buffer access. 


The fields image_types, write_image and interp_image have been removed from the options. 
Frame buffers are now specified in a database array of type miFb_info, which is field zmages- 
info in the options. 


The callback installed by the mz_disp_stream_cb_begin integration function receives a pointer 
of type miRc_mapfb instead of a tag array referring to milmg_image elements. A frame 


buffer can be accessed from the callback by using mi_disp_fbmap and mi_disp_fbunmap. 


The mi_query mode miRCQ_IMAGE has been removed. A new mode miRCQ_FB has been 
introduced that allows access to frame buffers. mi_rc_run_query returns a pointer of type 
miRc_maptb for this mode, which can be passed to mi_disp_fbmap and mi_disp_fbunmap 


for frame buffer access. 


Incompatible changes to the miInstance and miObject data structures have been made. 
The trace field has been removed, reflection, refraction, it transparency and finalgather fields 
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have been added. The shadow field is no longer treated as a boolean, it is interpreted as a 
bitmap which controls casting and receiving separately. 


e state — face is initialized with zero instead of using the value defined in the global options, 
allowing mental ray to distinguish between face flags set in the options, in the object or 
instance or overridden by the shader. 


e Some obsolete fields in the miGeoBox data structure have been removed. 
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Appendix A 


Command Line Options 


This appendix lists all commands in the mental ray suite. It is identical to the command line 
appendix of [Driemeyer 05]. Not all programs are available with all distributions. 


A.1 mental ray 


When started from a shell command line, the mental ray rendering software accepts a large number 
of options. Most of these correspond to similar commands or camera or options statements in 
the scene file. When an option is given on the command line, it overrides the corresponding 
command or statement in the scene file, which in turn overrides the defaults. The defaults for 
certain options given in the option list below apply only if the corresponding command or 
statement is not present in the scene file. 


mental ray is started as 
ray [options] [scenefile] 


If no scene file is given, the scene is read from standard input. Scene file names normally end in 
.mi. If the extension is missing mental ray will read the name as specified, and if this fails, retry 


with .mi added. 


Options can be abbreviated as long as the given substring is unambiguous. mental ray checks for 
ambiguities and prints an error message listing the choices. For example, -resolution can be 
abbreviated as -res. For frequently-used options such as -verbose and -filename, short forms 
are available. The page numbers on the right side refer to the relevant chapters in the main part 
of this book. The available options are: 


-acceleration bsp|largebsp| grid 
Selects the standard binary space partitioning (BSP) algorithm, or the large BSP 
algorithm that works for far larger scenes at a small performance penalty, or the 
voxel grid algorithm algorithm. The default is BSP. All these algorithms accelerate 
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-approx_displace [options] --> 
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ray tracing. 
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mental ray 3.1.2 and later allow specifying override approximations on the command 
line. Override approximations override any object approximations in the scene file. 
They are primarily useful for fast preview rendering, where approximation accuracy 
is not required. The following options can be specified: 


view view-dependent approximation 

fine fine approximation with microtriangles 

sharp faceted, useful for fine displacement 

parametric UV rectangular grid of U- V - 2 triangles 

regular U V rectangular grid that spans patches 

length L triangle edge length less than D 

distance D distance from true surface less than D 

angle A angle between neighboring triangles less than 
A degrees 

any it is sufficient if any of length, distance, and 
angle is satisfied 

min max subdivide at least min and at most max times, 
default 05 


Except for any, which must be spelled out, all options can be abbreviated by their 
first letter. If no options are specified (-approx --), parametric 0 0 is used, which 
produces a very fast low-quality approximation. See the scene description chapter 
for detailed information on approximations. 
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This option is similar to -approx and accepts the same options, but sets the override 
approximation for displacement. If no options are given, it defaults to parametric 0 0, 
which is so low that most displacements turn into a vaguely bumpy surface. High- 
quality displacement requires an approximation like -approx fine view length 
Bee OCT A, 


-aperture aperture 


The aperture is the width of the viewing plane. The height of the viewing plane is 
aperture divided by aspect. 


-aspect aspect 


This is the aspect ratio of the camera. The default is 1.33. In camera space, aperture 
is the width of the viewing plane, and aperture divided by aspect is the height. The 
viewing plane is divided into pixels as specified by the resolution viewdef, so the 
aspect will result in nonsquare pixels if it is not equal to the X resolution divided 
by the Y resolution. 


-bsp_depth depthin, 


The maximum number of levels in the BSP tree. This option is used only if binary 
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space partitioning is enabled. Larger tree depths reduce rendering time but increase 
memory consumption, and also slightly increase preprocessing time. The default is 
40. 


-bsp_memory memoryint 
The maximum memory in megabytes used in BSP preprocessing. A value of zero 
indicates that there is no limit on the memory consumption; this is the default. 


-bsp_size siZ€int 
The maximum number of primitives in a leaf of the BSP tree. Larger leaves will be 
subdivided unless the bsp_depth is reached. This option is used only if binary space 
partitioning is enabled. Larger leaf sizes reduce memory consumption but increase 
rendering time. The default is 10. 


-bsp_shadow on|off>! 
mental ray 3.1.2 and later support a separate shadow BSP tree that accelerates 
raytraced shadows. It can greatly 1 improve speed if shadows are cast by simplified 
shadow-only objects because it is no longer necessary to populate the master BSP 
tree with large hero objects. This mode is off by default. 


-caustic onloff 
Enable or disable the generation of caustics in an appropriately defined scene. The 
default is off. 


-caustic_accuracy mphotons [radius] 
The number of photons used to estimate caustics during rendering and the maximum 
radius to be used when picking up the photons. The number of photons may be set 
to 0, which means that all photons within the given radius are used. The defaults 
are 100 and a scene-size dependent radius. 


-caustic_scale r g b [a]}>* 
Caustics are multiplied by the specified color. Factors greater than 1.0 make the 
caustic brighter. 


-clip hither yon 
The hither (near) and yon (far) planes are planes parallel to the viewing plane that 
delimit the rendered scene for scanline rendering. Raytracing is not affected. Points 
outside the space between the hither and yon planes will not be rendered. The 
defaults are 0.001 and 1000000.0. 


-code "filename" ... -- 
The named filename is interpreted as a C source file (ending with the extension “.c” 
and compiled and linked into mental ray. 


-colorclip rgb|alpha|raw 
This option controls the rules used to clip an RGBA color before quantization to 
an 8-bit or 16-bit frame buffer. The rgb mode states that RGB are first to be clipped 
to the range 0, 1] before A is clipped to [max(R, G, B), 1]. This is the default mode. 
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The alpha mode lets A first be clipped to [0, 1] before RGB is clipped to [0, A]. Both 
of these modes ensure that all channels are within [0,1] and that A is no less than 
any of R, G, and B, which is is the valid domain of premultiplied colors. The third 
mode, raw, ignores all requirements, and clips both A and RGB to {0, 1]. This is 
useful to make mental ray modify output colors as little as possible. Because the 
color output may be invalid, the raw mode overrides the premultiply off option 
if present. Desaturation is always applied if enabled. 


-contrast r g b [a] 


The contrast controls oversampling. If neighboring samples differ by more than 
the color 7, g, b, a, oversampling is done as specified by the sampling options. The 
default is 0.1 0.1 0.1 0.1. If missing, the default for a is the average of r, g, and D. 


-c_compiler "filename" 


If this option is given, the standard C compiler "cc" is replaced with filename. 


-c_flags "options" 


The options string replaces the standard options given to the C compiler. The defaults 
depend on the machine type. If the options begin with two plus signs”"', such as 
"++ -I.", it is inserted into the default options instead of replacing them. 


-c_linker "filename" 


If this option is given, the standard linker "1d" is replaced with filename. 


-desaturate onloff 


Ifa rendered sample returns an RGBA color whose components are outside the legal 
range, mental ray will clip the color into this legal range. This option determines 
how the clipping of R, G, and B is performed. If desaturation is turned off, which 
is the default, the components are clipped individually. If turned on, then if any of 
R, G, and B exceed the allowed range, the color is shifted towards the grayscale axis 
of the color cube in order to try to maintain the perceived brightness of that color, 
effectively bleaching out the color. The valid range of RGBA is controlled by the 


colorclip option. 


-diagnostic bsp depth|size 


This diagnostic mode’ can be used to visualize the parameters for BSP tree 
parameters (see -bsp depth and -bsp size options), to find the reason for 
unexpected large depths or sizes reported after rendering. This does not work 
in -acceleration largebsp mode because that mode never creates a single BSP 
tree from which consistent diagnostics could be computed. 


-diagnostic grid off|object|world|camera size 


This diagnostic mode"! is intended for scene debugging. Unless set to of f, it draws 
a colored grid on all objects in the scene that shows object, world, or camera space 
coordinates. Steps on the X, Y, and Z axes are shown with red, green, and blue grid 
lines, respectively. The distance between grid lines is szze units. This is useful to 


'The -diagnostic bsp option requires mental ray 3.0 or higher. 
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estimate the size and distances between objects in mental ray, or to visualize object 
space coordinates. The off argument disables the grid. The default is off. 


-diagnostic hardware [ window] grid ]°* 
Hardware rendering diagnostics. Without argument, turns off shading and uses a 
default gray material. The window mode pops up a window on the screen, showing 
rendering progress. The grid mode renders a wireframe scene. 


-diagnostic photon off|density|irradiance max 

When rendering caustics or global illumination, this option disables all material 
shaders in the scene and produces a false-color rendering of photon density, or the 
average of the red, green, and blue irradiance components. Photon density is the 
number of photons per unit surface area. max is the density (or irradiance) that 
is assigned to 100%, or red. The colors are, from 0% to 100%: Blue, cyan, green, 
yellow, and red. Higher values fade to white. max can be given as zero in which 
case the appropriate maximum is automatically found. This is done after the whole 
image has been rendered. This mode is useful when tuning the number of photons 
in a photonmap and setting the various _accuracy options, since the density (or 
irradiance) is estimated using those settings. The default is of f. 


-diagnostic samples on|off 
Switch to sampling visualization mode and create grayscale images representing 
sampling densities instead of color images. A black pixel has had no samples, whereas 
a white pixel has had the maximum amount as specified by the -samples option. 
In addition, a red grid shows task rectangle boundaries. 


-diagnostic finalgather?'! 
This mode shows final gathering points, as green dots for initial raster-space final 
gathering points, blue dots** for final gathering points from per-object finalgather 
map files, and red dots for render-time final gathering points. 


-displace onloff 
Ignore all displacement shaders if set to off. The default is on. 


-displace_presample on|loff>? 
Enables or disables presampling of displacement-mapped geometry. Presampling 
increases performance by introducing a preprocessing phase before tessellation, and 
is enabled by default. If turned off, rendering begins earlier but takes longer; this is 
sometimes useful for preview rendering. 


-dither on|off 
Ditheringdithering mitigates 8-bit and 16-bit color quantization errors by intro- 
ducing noise into the pixel such that the round-off errors are randomly distributed. 
The default is off. 


-echo "filename" [ascii] [source] [approx] [norendercommand] [textures] [incremental>] 
[omit "S"][norecurse "S"] [explode [N]] -- 
Echo the current scene to the file filename. The options specify the format of the 
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echoed file. Allowed options are: 

ascii uses ASCII format for the vectors (default is binary), 
source prefers source geometry over triangles if available (default), 
approx prefers triangles over source geometry if available, 
norendercommand disables the echo of the render command, 
textures includes texture pixel data verbatim. 


incremental’? causes multiframe animations to be echoed in a more compact 
format, by omitting scene elements that did not change since the previous frame. 


omit specifies that certain types of elements, specified by S, should be omitted 
from the output. It is supported by mental ray 3.0 only. Note that both omit and 
norecurse will produce incomplete and nonrenderable scene files. These options 
are useful for extracting subsets of a scene. 


norecurse specifies that references of certain types of elements specified by S should 
be omitted from the output. It is supported by mental ray 3.0 only. For example, if 
S contains icil, instances of cameras and lights would be echoed (unless disabled 
by omit), but the instanced camera or light would not be echoed first. The S strings 
of the omit and norecurse attributes are sequences of the following codes: 


instance group instgroup 
geometric object object 
camera camera 
light source light 
material material 
texture texture 
option block options 
named shader shader 
declaration declare 
user data data 
instance of an instance group | instance 
instance of an object instance 
instance of a camera instance 
instance of a light instance 
instance of a geometry shader | instance 


& 
O 
Cc 
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Note that triangle echos have displacement mapping already applied to the triangles, 
but the displacement shaders are not removed from the materials so the echoed file 
will get displaced twice when rendered. The echo option must be terminated with 
a double minus. 
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explode causes all objects with more than N vertices to be written to a separate file 
with a name beginning with autoload. This file will be referenced by a placeholder 
object with an appropriate file statement in the main echo file. If omitted, N 
defaults to 1; a typical good value is 10000 to make sure that the overhead of 
opening a file is not wasted on really small objects. 


-face front|back| both 


-fb_dir "directory 


-file name 


-file_type 


The front side of a geometric object in the scene is defined to be the side its normal 
vector points away from. By specifying that only front-facing triangles are to be 
rendered, speed can be improved because fewer triangles need to be tested for a ray. 
The default is face both. 


"13.4 


Specifies a directory for temporarily storing memory mapped frame buffer files. 
mental ray 3.4 and later store frame buffers in files on disk, not in memory, to 
conserve space. If this option is not provided, the environment variables TMPDIR 
and TEMP are examined. If they are also not defined the current working directory 
is used for storing memory mapped frame buffer files. 


"filename" 

Overrides the file name given by the first file output statement in the camera 
definition in the scene file. The full file or path name must be given, including 
extension if desired. 


"format" 

Overrides the file format given by the first file output statement in the camera 
definition in the scene file. File formats include "pic" for Softimage image files, 
"rla" for Wavefront RLA files, and "ps" for PostScript files if contour mode 1s 


enabled. 


-filter [ clip’? ] box|trianglelgauss|mitchell|lanczos width [height] 


This option specifies how multiple samples in recursive sampling mode are to be 
combined. The filter defaults to a box filter of width and height 1. The filter size can 
also be specified, in pixel units. Good filter sizes are 1.0 for box, 2.0 for triangle, 
3.0 for gauss, and 4.0 for mitchell and lanczos. mental ray 3.2 and up also 
support clip mitchell and clip lanczos to clip the filter result to the sample 
range under the filter, which avoids ringing in these filters because they contain 
negative coefficients. In mental ray 2.0, this option requires a sampling density of 
at least 1 1; in mental ray 2.1 and later the sampling density must be at least -1 0. 


-finalgather on|off|only°’’|fastlookup 


Enables or disables final gathering*"'. It is disabled by default. Final gathering is a 
rendering technique used for computing indirect illumination with a one-generation 
raytracing step. mental ray 3.0 adds a third choice, fastlookup, that enables final 
gathering and also arranges for irradiance to be stored in the photon map. This 
slows down photon tracing but greatly accelerates final gathering. mental ray 3.3 
adds the only keyword, which computes the finalgather map and skips rendering. 
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-finalgather_accuracy [view] nraysin, [ maxdist [ mindist ]] 
nrays is the number of rays cast in a final gathering step during rendering. The 
default is 1000. maxdist is the maximum distance within which a final gather result 
can be reused. The default is scene dependent. mindist is the minimum distance 
within which final gather results must be reused. The default is scene dependent. 
Both distances are specified in world space units, or raster space units if view™ is 
specified. 


-finalgather_depth reflectj,, [ refractin, [ diffuse?* in [ sumim |]}°? 

This option is similar to -trace_depth but applies only to finalgather rays. The 
defaults are all 0, which prevents finalgather rays from spawning subrays. This 
means that indirect illumination computed by final gathering cannot pass through 
glass or mirrors, for example. A depth of 1 (where the sum must not be less than the 
other two) would allow a single refraction or reflection. Diffuse bounces?* can also 
be controlled. It is not normally necessary to choose depths greater than 2. This is 
not compatible with mental ray 3.1 and earlier, which used the trace depth (which 
defaults to 2 2 4) for final gathering. 


-finalgather_display onloff>*? 
Allows image previewing during the finalgather presampling stage if the imf_disp 
viewer is attached to the output image file. This is disabled by default. The quality of 
the preview image is very low, but it allows fast detection of illumination problems 
in a scene. This option has no impact on the final image. To improve performance 
it is recommended to disable this option for non-interactive rendering. 


-finalgather_falloff [start] stop’? 
Limits the length of final gather rays to a distance of stop in world space. If no object 
is found within a distance of stop, the ray defaults to the environment color. The 
start parameter defines the beginning of a linear falloff range; objects at a distance 
between start and stop will fade towards the environment color. This option is useful 
for reducing memory usage for the geometry cache. 

-finalgather_file "name"? 
Tells mental ray to use the file filename for loading and saving final gather points. If 
the finalgather file does not exist, it is created and the final gather points are saved. 
If it exists, it is loaded, and the points stored in it become available for irradiance 
lookups. If mental ray creates extra final gather points, they are appended to the 
file. This means that the file may grow without bounds. 

-finalgather_file [ "name" "name" ... ]>“ 

mental ray 3.4 and later allow attaching a list of finalgather file names instead of a 

single file name from a command line. All files are read and merged. The first file is 

rewritten with the complete map like in the single-file case. 


-finalgather_filter size;,,>? 
Final gathering uses an speckle elimination filter that prevents samples with extreme 
brightness from skewing the overall energy stored in a finalgather hemisphere. This 
is done by filtering neighboring samples such that extreme values are discarded in the 
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filter size. The default is 1; 0 turns speckle elimination off and greater values remove 
more speckles and soften contrasts. Sizes greater than 4 or so are not normally 
useful. 


finalgather_presample_density ion 
This option controls the density of initial finalgather points created during 
preprocessing (green dots in the diagnostic image). It increases (decreases if T < 1) 
the number of precomputed finalgather points approximately 7 times. 
-finalgather_rebuild on|off|freeze>” 
If a flename is specified using the -finalgather_file option, it is normally loaded 
and used if the file exists. -finalgather_rebuild on causes existing files to be 
ignored, all final gather points will be recomputed and an existing file will be 
overwritten. freeze is equivalent to on, except that the final gather map, once 
created by reading it from a file or building it in the first frame, will never be 


modified. Extra finalgather points created during rendering will not be appended, 
and the finalgather file on disk will not be modified. 


-finalgather_scale r g b [a]>* 
The irradiance obtained from final gathering is multiplied by the specified color 
making the irradiance effect brighter for factors greater than 1.0. 


-focal distance|infinity 
The focal distance is set to distance. The focal distance is the distance from the 
camera to the viewing plane. The viewing plane is the plane in front of the camera 
that the rendered scene is projected onto; its edges correspond to the edges of the 
rendered image. If infinity is used in place of the distance, an orthographic view 
is rendered. 


-gamma gamma_factor 
Gamma correction can be applied to rendered color pixels to compensate for output 
devices with a nonlinear color response. All quantized R, G, B, and alpha component 
values (ie. not if the frame buffer is floating-point or RGBE) are raised to gamma- 
factor. The default gamma factor is 1.0, which turns gamma correction off. The 
reverse correction is applied to all quantized texture images. 


-geometry on|off 
Ignore all geometry shaders if set to of f. The default is on. 


-globillum on|off 
Enable or disable the computation of global illumination?'. The default is off. 
To actually compute global illumination, lights must have an energy, and materials 
must have photon shaders. 


-globillum_accuracy nphotonsin, [radius] 
The number of photons used to estimate global illumination during rendering 
and the maximum radius to be used when reading photons during rendering. The 
defaults number of photons is 500. If mphotons is set to 0, all photons within the 


718 A Command Line Options 


given radius are used. The default radius is scene size dependent. 


-globillum_scale r g b [a]* 
The irradiance obtained from the globillum photonmap lookup is multiplied by the 
specified color, making the effect brighter for factors greater than 1.0. 


-grid_depth depthj,,>' 
If the hierarchical grid algorithm? is used, this option sets the number of recursion 
levels. If a voxel of a grid contains too much detail, it is subdivided by a subgrid for 
that voxel, which adds another level. 


-grid_resolution xresj,; Lyresint ZVCS p+ 
If the hierarchical grid algorithm®' is used, this option sets the number of grid 
voxels in the X, Y, and Z dimensions. If only one number is given, it is used for all 
three dimensions. The default is 0 0 0, which selects a default computed at runtime. 


-grid_size factor 
If the static grid algorithm?! is used, factor is a correction factor for mental ray’s 
internal guess for the grid resolution, so that numbers greater than 1.0 increase the 
number of voxels in each dimension and numbers less than 1.0 decrease it. 


-grid_size sizéjn, 
If the hierarchical grid algorithm?" is used, this option sets the maximum number 
of triangles in a grid voxel. If there are more, and the grid depth permits it, the voxel 
is subdivided into a subgrid. 


—H "path">* 
Specifies the directory where hardware shaders are located. This is a shorthand for 
-hardware_path ". 
-hardware offlonlall --°° 
Specify which objects should be rendered with hardware rendering: off disables 
hardware rendering (this is the default), on uses hardware rendering for all materials 
that specify a hardware shader, and all uses hardware rendering for all objects 
and tries to find hardware substitutes for materials that do not specify an explicit 
hardware shader. The most useful mode is all. Note that this option only selects 
which objects are eligible for hardware rendering, but mental ray may still fall back 
on software rendering for objects for which no appropriate hardware shaders are 
available. This is controlled separately by the following options. 


-hardware cgl|nativelfast* -- [force }° 
This option controls how hardware shaders are selected for an object that 1s eligible 
for hardware rendering, as specified by the previous option. mental ray will try all 
approaches allowed by this option in turn: 


cg means that mental ray will first look for shaders implemented in NVIDIA’s Cg 
1.2 shader programming language. This is the default. 
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native looks for shaders implemented in the OpenGL 2.0 native shader program- 
ming language, which is less powerful than Cg. 


fast uses hardcoded OpenGL materials that do not involve programmable shaders 
at all. This is limited to simple Gouraud models. 


force specifies that the search stops here, and objects that cannot use any of the 
above methods use a simple gray default material. If force is not specified, mental 
ray will fall back on software rendering for the object. 


The hardware options can be combined. For example, ~hardware all cg native 
fast force -- will render all objects with the best available hardware shading 
method but never with software; this is useful for fast preview rendering. The 
option ~hardware all cg native -~ is best for quality rendering, and so on. 


-hardware_echo [error] "path" 


Write the Cg source code as it is passed to the Cg compiler and the resulting assembly 
code to disk, to the directory path. If the error option is specified, only those files 
are written for which compilation has failed. This is useful for debugging, and to 
extract shader code from mental ray for use in game engines or other standalone 
applications. 


-hardware_path "path"?* 


Specifies the directory where hardware shaders are located. Can also be abbreviated 
as =H. 


-hardware_samples mutlttin; superint 


-help 


Specify the multisampling and supersampling rates to be used for hardware 
rendering. Multisampling is done by the hardware pixel pipeline, which takes 
more samples per triangle and writes the result to the frame buffer. Supersampling 
is done by mental ray, by increasing the frame buffer size and rendering at a 
higher resolution, and then downfiltering to the requested frame buffer resolution. 
Multisampling is much faster and does not increase hardware video memory usage 
(or even exceed the GPU resolution capacity), but supersampling looks better. 


Print a summary of all options with their allowed parameters, and terminate. 


-hosts "hostname[:portnumber] [ remote parameters" ... -- 


The machine list overrides the machine list taken from the . rayhosts file, if present. 
One slave is started on each machine specified. Machine names must be given as 
expected by the local name resolving method (such as /etc/hosts) or as a numeric 
IP address (nnn.nnn.nnn.nnn). 


-I "path1:path2...." 


Overrides the path used to resolve $include commands in the .miscene file. The de- 
fault path contains the directories ., {_-MI-REG_INCLUDE}, /usr/local/mi/rayinc, 
/usr/include, and /usr/include/mi. Note that only one -I option can be spec- 
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ified. It may contain a colon-separated (Unix only) or semicolon-separated (Unix 
and Windows NT) list of directory paths that are tried in sequence if a $include 
command using angle brackets is used in the .mi scene file. Paths introduced with 
an exclamation point are special; they are applied to quoted $include paths too, 
and substitute the entire directory path. This can be used to force mental ray to 
use a specified path regardless of the path specified in the $include command, for 
example because that path points to an obsolete (1.9) version of a declaration file. 
For example, -I /a:/b:!/new tries to find a path <x/y/z> first as /a/x/y/z, then 
/b/x/y/z, then /new/z. 


-imgpipe fain: 
Normally mental ray prints connection information into the output image file that 
let programs like imf_disp connect and display images while being rendered. If 
-imgpipe is used, the relevant information is printed to the given file descriptor fd 
instead. This can be used for command lines such as “ray -imgpipe 1 scene.mi 
| imf_disp -”. The imf_disp program is a viewer provided by mental images that 
supports image piping. 


-jitter jitter 
The jittering factor introduces systematic variations into sample locations if jitter is 
set to 1.0. Jittering is turned off by default, or by specifying a jitter of 0.0. 


-jobmemory mb 

The physical argument specifies the size of mental ray 3.x’s scene cache memory, 
in megabytes. The default is unlimited for mental ray 3.0 and 512 for mental ray 
3.1. (mental ray 3.1 supports fine microtriangle tessellation which depend on the 
ability to flush obsolete triangles from the cache.) The virtual number of megabytes 
limits the amount of virtual address space available for memory mapping, mostly 
for memory mapped textures; the default is 1024 (1 GB) on 32-bit machines and 
0 (unlimited) on 64-bit machines. This option has been obsoleted by -memory in 
mental ray 3.2. 


-L "path1:path2...." 
This is an abbreviation for -1d_path. 


-ld_libs "libraries" 
The libraries string replaces the standard library options given to the linker. The 
defaults depend on the machine used, typically "-1lm -1c". Linker options are 
machine dependent and operating system dependent and cannot be changed. 


-ld_path "path1:path2...." 
Supply a list of library search paths that mental ray searches for shader libraries 
containing shader code. The paths given here precede those that can be given by the 
environment variable MI-LIBRARY_PATH and the built-in search path (consisting of 
the directories {_MI_REG_LIBRARY}, /usr/local/mi/1lib, and .. 


-lens on|off 
Ignore all lens shaders if set to of f. The default is on. 
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-lightmap on|off|only?* 
This mode enables rendering of lightmaps. By default, lightmaps are enabled. If this 


option is set to only, only the lightmaps but not the camera images are rendered. 


-link "filename" ... -- 
Like the code command, the link command attaches external shaders to mental ray, 
which can then be used as shading functions. While the code command accepts “.c” 
files as filename, the link command expects either object files ending in “.o” or 


“obj”, or shader library files ending in “.so” or “.dll”. 


-maxdisplace dist’? 
This option overrides all max displace values in scene objects with dist if dist > 0. 
This is useful to render old scene files built for mental ray 1.x or 2.x, which did not 
support max displace, and so would fail to show any displacement when rendered 
with mental ray 3.x. 


-memory limit? 
The /imit argument specifies the size of mental ray 3.2’s total memory usage in 
megabytes, including heap (non-scene data), scene database, and virtual memory. 
The default is 512 megabytes. This option replaces -jobmemory in mental ray 3.1. 
Swap space specified with -swap_limit is not included. Memory limits have no 
effect on slave hosts, which do not have a command line. 


-message module class_list ... -- 

Enable or disable individual message classes, per module. The module names are 
printed at the beginning of every message printed by mental ray; all can be used to 
modify the message classes of all modules. The class_list is a comma-separated list of 
classes to print. Supported message classes are phase, progress, vprogress, time, 
scene, memory, render, vrender, resources, network, files, and debug. The 
special words default, all, and none are also supported. A class can be inverted 
by prepending an exclamation point. For example, to print less verbose RC progress 
messages and make all modules report every file accessed, specity 


-message rc default,!vprogress all default,files -- 


The message codes that perform useful actions are listed in the following table: 
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—-motion 


msgtrans 
debug 

progress 
tessellate 


files 
debug 
resources 
files 
progress 
network 
progress 
debug 
phase 
scene 
debug 
phase 


resources 


debug 
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network transfers 

add comments to -echo incrementa 
tessellation and displacement sampling 
triangles created by tessellation 
opened files 

job execution, slave transfers, status 
post-render job execution statistics 
opened include files 

line numbers every 50000 lines 

slave host rendezvous details 

host list, connecting hosts 

check shader results for NaN (Not a Number) values? 
rectangle rendering begin and end 
camera/option dump before rendering 
BSP subtree and grid creation®* 
preprocessing, geometry shaders 
postprocessing statistics 

echo MI declaration equivalents 


132 


output 


on|off>? 


Normally the -shutter option controls whether motion blurring is enabled, and 
turns it on if there is a nonzero shutter interval. The -motion option overrides this 
and turns motion blurring on or off explicitly. For example, it is useful to define a 
zero shutter interval and then (order is important) turn motion blurring on, so that 
shaders get a correct state —> motion vector. If motion blurring is turned off, this 
vector is not computed. 


-motion_steps steps*' 


-nomaster”’! 


Approximate instance motion transformations with steps segments. This results in 
a smooth motion path, as if a similar number of motion vectors had been specified. 
steps must be a number between 1 and 15; 1 is the default. If objects with motion 
transformations also specify motion vectors, the number of motion vectors per 
vertex must agree with the motion steps value. 


When rendering with multiple hosts, schedule all jobs on slaves only, if possible. 
For example, the master host will not render, tessellate, compute shadow maps, 
etc, if possible; but it will still load textures of the slaves, and will also collect and 
save rendered images. The master may execute certain rendering jobs only if the 
slaves run out of resources. This is useful if the master host also runs front-end 
applications that must remain responsive even under heavy load. 


-o "filename" 


-offset x y 


This is an abbreviation for -file_name. 


An offset for the rendered image. The default is 0.0 for both x and y, which means 
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that the image will be centered on the camera’s Z axis. Positive values translate the 
image up and to the right. The offset is measured in pixel units. 


-output onloff 
Ignore all output shaders if set to of f. The default is on. File output statements are 
not affected. 


-photonmap_file "filename" 
Use filename for the photon map, in all frames. If the photon map file does not 
exist, it is created and saved. If it exists, it is loaded and used. For multiple frames it 
is only created for the first frame and then loaded for the remaining frames, which 
can greatly speed up rendering in scenes where the illumination does not change 
much, such as camera flythroughs. 


-photonmap_only on|off>* 
If this option is set, only the photon maps but not the camera images are rendered. 


The default is off. 


-photonvol_accuracy nphotonsin, [radius] 
Controls how global illumination or caustics in participating media are estimated 
by looking up the photon map during rendering. mphotons is the maximum number 
of photons to examine and radius the maximum radius to search. if nphotons is 0, 
all photons are examined up to the radius limit. A radius of 0 means that a scene 
size dependent radius will be used. The defaults are 30 and 0.0. 


-photon_depth reflectin, [refractin, [sumint]] 
photon_depth is similar to trace_depth except that it applies to photons. If set to 
0, no photons will be reflected; if set to 1, one level is allowed but a photon cannot 
be reflected again, and so on. The defaults are 5 5 5. 


-premultiply on|loff 
Premultiplication means that colors are stored with alpha multiplied to R, G, 
and B. This is the default. For example, white at 10% opacity is not stored as 
(1, 1, 1, 0.1) but as (0.1, 0.1, 0.1, 0.1). If turned off, mental ray writes the colors 
without premultiplication; in this case color clipping should also be switched to 
raw mode. 


-render beginin, [ endin: [ inCint |] 
Render only frames begin through end?. If end is omitted, begin and all following 
frames are rendered. If imc is given, only every inc-th frame is rendered. Frame 1 
is considered the first render statement in the scene file; camera frame specifiers 
are not considered. For example, 4 8 2 will skip the first three frames, then render 
frame 4, 6, and 8, and omit the rest. It is not an error if the scene file has fewer 
frames than requested. 


-resolution Xint Vint 
Specifies the width and height of the output image in pixels. The default is 768 576. 


The -render option was introduced in mental ray 2.1.36. 
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-samplelock onloff 
This option selects whether sampling of area light sources, motion blur, and depth- 
of-field is static or dependent on the frame number. The default is on (static). 


-samples MINjnt MaXint 
This option determines the minimum and maximum sample rate. Each pixel is 
sampled at least (27”””) and at most (27) times in each direction. If min is 0, each 
pixel is sampled at least once. Positive values increase the minimum sample rate; 
negative numbers reduce the sample rate. The default is -2 0. 


-samples Mining MaXinx defminin, defmaxin' 
mental ray 3.1.2 accepts two optional extra parameters that set the default object 
sample limits. In mental ray 3.1.2, objects may constrain sampling of the pixels they 
cover. The defmin;,,; and defmax;,,; parameters apply to pixels where no objects are 
seen, or all the objects that are seen have no samples limit. mental ray will never 
take fewer than 2””” and more than 2”* samples, and in areas with no object sample 
settings it will further reduce that range to 27/”” through 24/"**, The defaults are 
—2 0 -128 127; the latter two are markers for “no further restrictions” because they 
are outside the —2 0 range. 

-shading_samples num?” 
Rasterizer (formerly called Rapid Motion) sampling is controlled by the -shading_ 
samples option. The units are shading samples per pixel, and the default is 1.0. 

-samples_collect num>? 
The rasterizer adds a separate collection phase after tile rendering that combines 
subpixel samples to pixels. The xum argument controls how many shading points 
should be used for compositing one pixel. Unlike the -samples arguments, the num 
argument is a linear count per pixel dimension, x and y. The default is 4, which gives 
16 samples per pixel. The rasterizer (formerly known as Rapid Motion) no longer 
uses the -samples option. Rasterizer sampling is not adaptive. 

-samples_motion NUM int? 

Determines at how many points in time a moving object is shaded in rasterizer 

(Rapid Motion) mode. The default is 1, which means that a moving object is sampled 

once at shutter open time, and this result is blurred across the motion path. Higher 

values than 1 sample at more points during the shutter interval. This option does 

not apply to regular scanline rendering because it does not cache shading results. 


-scanline on|off|opengl|rasterizer|rapid 
Mode off allows turning off the scanline rendering algorithm to force mental 
ray to rely exclusively on ray tracing. This will slow down rendering in most 
cases. The rasterizer mode?* enables a different algorithm that greatly improves 
motion blurring speed. It is synonymous with rapid’; the term “Rapid Motion” 
is deprecated in favor of “rasterizer” because the rasterizer is a full rendering 
algorithm, not only a motion blurring accelerator. The opengl mode uses local 
OpenGL hardware to accelerate rendering, which sacrifice some accuracy for a 
large speed gain. If shadow mapping is also used, -shadowmap openg1 should also 
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be chosen. See page 93 for more information. The default scanline mode 1s on. 
-scanline_collect num’? 
Rasterizer (formerly known as Rapid Motion) shading is controlled by the second 
argument of the -samples option, which is also used by all other rendering 
algorithms. The rasterizer has a separate collection phase that composites samples 
to pixels. The mum argument controls how many shading points should be used 
for compositing one pixel. Unlike the -samples arguments, the zum argument is a 
linear count. The default is 274*=77"?"*s, 


-shadow off|on|sort|segments 
Choose the shadow mode, or disable shadows. The default is on. 


off disables all shadows, including shadow maps. 
on enables standard shadows. 


sort enables shadows and sorts shadow intersections before calling shadow shaders. 
Some shadow shaders require this. 


segments enables shadows and traces shadow rays like visible rays. Some shadow 
shaders require this. 


-shadowmap [on| off |openg1] [only] [rebuild] [reuse] [motion] [nomotion|] -- 
This option can be used to control shadow maps. The option list is a sequence of 
one or more keywords. 


on activates use of shadow maps. 
off disables use of shadow maps. This is the default. 


openg1 enables use of shadow maps, and uses local OpenGL hardware to accelerate 
shadow map rendering, at a small accuracy loss. See also page 93 and -scanline 
opengl above; it often makes sense to enable OpenGL in both options. 


only causes only shadow maps to be rendered, without rendering a color image. 
By default the color image is rendered also. This is useful to precompute shadow 
maps before the actual color rendering passes begin. This does not work with detail 
shadowmaps> because detail shadowmap files only store shadowmap tiles that 
were needed during rendering. 


rebuild causes all shadow maps to be recomputed, even if they exist in memory 
from a previous frame or are found on disk. By default shadow maps are computed 
only if they are found neither in memory nor on disk. 


reuse allow the reuse of shadowmaps. This is the default. If a shadowmap 1s found 
in memory or on disk it is used instead of recomputing it. This only works if object 
space mode is selected in the options block of the scene. 
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motion activates motion blurred shadow maps. This is enabled by default if shadow 
maps are turned on. 


nomotion disables motion blurred shadow maps. This improves rendering speed. 


merge’ specifies that if the shadowmap was saved to disk (using a shadowmap 
file statement in the light description), this file should be read. Whenever a 
regular shadowmap computation shows that a shadow-casting object is closer to 
the light than the shadowmap on disk specifies, the closer value is used; otherwise 
the shadowmap remains unchanged at that point. This can be used to build up 
shadowmaps for multipass rendering. 


-shutter [ delay | shutter 


-swap_dir "directory 


-swap_limit size 


This option controls motion blurring. The camera shutter opens at time delay"! and 
closes at time shutter. The defaults are both 0.0. If shutter is equal to delay, motion 
blurring is disabled; if shutter is greater than delay, motion blurring is enabled. 
The normal range is (0, 1), which uses the full length of the motion vectors or 
motion vector paths>:!. It can be useful to set delay*:' and shutter both to 0.5, which 
disables motion blurring but renders with an offset of one half frame, which allows 
bidirectional post-blurring in an output shader. 


13.2 


Specifies a directory for disk swapping. When mental ray runs out of memory, it 
can push memory objects to disk, and load them back when they are needed again. 
mental ray does this much more efficiently than the operating system, which has no 
semantic knowledge of the data. For example, source geometry is not likely to be 
needed anytime soon, or at all, after it has been tessellated. The directory should be 
on a local disk, not a file server. This option should be used together with -swap- 
limit, and given before -swap_limit on the command line. 


3.2 


Specifies the number of megabytes to write to the swap directory specified with 
-swap_dir. This space effectively becomes an extension of system memory. The 
default is 0, which turns off swapping. Good numbers are in the low thousands. 


-T "path1:path2...."°* 


Specifies a list of directories where texture files will be searched. The default 
is the current directory. The list is colon-separated (Unix only) or semicolon- 
separated (Unix and Windows NT). As with the -I option, paths introduced with 
an exclamation point are special: they substitute the entire directory path of the 
texture name and keep only the last component (the file name) when searching. 


-shutter shutter 


This option specifies the shutter open time. A shutter value of 0.0 turns motion 
blurring off, values greater than 0.0 turn motion blurring on. The standard value for 
enabling motion blurring is 1.0; larger values increase the blur length. The default 
is 0.0. 
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-task_size task_sizejn 
This option specifies the size of the image rectangles during rendering. Smaller task 
sizes are convenient for previewing, but also increase the overall rendering time 
and reduce the effectiveness of edge following. This option can also be used to 
optimize load balancing for parallel rendering. If the task_size is not specified, an 
appropriate default value such as 32 is used. 
-texture_continue’” 
Normally, standalone versions of mental ray abort as early as possible when a texture 
file cannot be read, to avoid spending a lot of time on unusable images and letting 
the farm controller know as soon as possible. If this option is specified, mental 
ray will continue and use transparent black or red-and-black checkerboard defaults 
(depending on the shader) for missing texture files. 


-threads nthreads;,, 
Normally, mental ray starts one thread for each processor in the system. The number 
of threads can be changed with this option. mental ray will create more threads than 
specified, but only nthreads;,, will perform compute-intensive tasks simultaneously. 
In mental ray 3.3 and later, this includes threads on hyperthreaded Intel CPUs, 
which do not consume licenses. For example, a two-processor hyperthreaded Xeon 
system would run four threads and pull two licenses. 


-time_contrast 7 g b [a] 
The time contrast controls the amount of temporal oversampling for motion blurred 
scenes. The number of temporal samples is approximately proportional to the 
inverse of the time contrast value. The default is 0.2 0.2 0.2 0.2. For fast motion 
blur, an alternative non-adaptive sampling technique can be used by setting the 
time contrast to 0 0 0 and minimum and maximum sampling to the equal relatively 
high value, such as 2 2. 


-trace onloff 
Normally, mental ray will use a combination of a scanline rendering algorithm and 
ray tracing to calculate samples of the scene. If -trace off is specified, ray tracing 
is disabled, and mental ray will rely exclusively on the scanline algorithm. 


-trace_depth reflectin, [refracting [sumint]] 
reflect limits the number of recursive reflection rays. If it is set to 0, no reflection 
rays will be cast; if it is set to 1, one level is allowed but a reflection ray can not 
be reflected again, and so on. Similarly, refract controls the maximum depth of 
refraction and transparency rays. Additionally, it is possible to limit the sum of 
reflection and refraction rays with sum. The defaults are 2 2 4. 


-v on|off |level;,, 
An abbreviation for -verbose. 


-verbose onloff |/evel;,, 
This command controls verbose messages. There are seven levels: fatal errors 
(1), errors (2), warnings (3), progress reports (4), informational messages (5), 
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debugging messages (6), and verbose debugging messages (7). All message categories 
numerically equal to or less than /evel are printed. Verbose of f is equivalent to level 
2 (fatal errors and errors); verbose on is equivalent to level 5 (everything except 


debugging messages). 


-volume on|off 
Ignore all volume shaders if set to off. The default is on. 


-window xlowin, ylowin xbighin ybighin 
Only the sub-rectangle of the image specified by the four bounds will be rendered. 
All pixels that fall outside the rectangle will be left black. This option does not have 
an affect on the size of the frame buffer or saved image files; it merely suppresses 
rendering pixels outside the window. 


-xcolor ["control"] 
Print colored messages. Error messages, for example, are printed in red, which 
makes them stand out much better in verbose reports. The control string allows 
customization. 


A.2. Inventor mental ray 


Inventor 1s a real-time 3D scene viewing technology introduced by Silicon Graphics. There 1s a 
version of mental ray called ivray that has Inventor support built in. It can be used to read scene 
files and display and manipulate them in realtime on the screen, and rendering and writing them 
back to disk. Since OpenGL and Inventor do not support custom shaders, very simple shaders 
are used for the realtime display. Although ivray can be used like a regular mental ray executable, 
this is not recommended because it is larger and takes slightly longer to start up. ivray up to 3.2 is 
supported for Silicon Graphics systems only. ivray 3.3 and higher is available for Silicon Graphics 
and Linux. The following additional command line options are supported: 


-inventor 
Enables the realtime Inventor viewing window. ivray will read the scene file up to the 
first render command and then create the Inventor window instead of rendering. 


-ivdrawstyle S, 5S) 
Static and moving objects will be drawn using styles S; and $3, respectively. Available 
styles are shade (shaded), wire (wireframe), and box (bounding box). The default 
is Shade wire. 


-ivleaf onloff 
If on, use the leaf instance list to collect objects instead of replicating the mental 
ray scene graph as an Inventor scene graph. This is useful for scenes with multiple 
instancing. The default is off. 


-ivout "filename" 
Write the scene as an Inventor scene file named filename. 
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-ivrendercache on|off 
Enable or disable Inventor object caching. This is on by default. 


-ivstrips on|off 
Enable or disable triangle strips. Strips slightly increase tessellation time but can 
significantly improve display performance. Strips are enabled by default. 


A.3. Environment Variables * 


Environment variables can be set from a shell prompt with shell commands such as setenv (see 
the documentation of your shell) before mental ray, ivray, or the application that mental ray is 
built into, is started from the same shell. Environment variables set after mental ray is started, or 
set from a different shell, have no effect. mental ray will work without any environment variables, 
except that the .rayrc startup script may not be found if MI_ROOT is undefined. 


DISPLAY 

The Unix X11 display to be used for OpenGL acceleration. 
HOME 

Unix home directory, for finding the user’s local .rayrc file. 
HOMEDRIVE 

Windows NT home drive, such as C:. 
HOMEPATH 


Windows NT home directory. mental ray will try to load 
/HOMEDRIVE//ZHOMEPATH?,/rayrc. 


MI_CG_FRAGMENT_PROFILE?* 
Pass this profile name to the Cg compiler when compiling hardware 
shaders, instead of the profile matching the graphics hardware 
rendered on. This is useful in conjunction with the ~-hardware_echo 
command-line option to “cross-compile” shaders. 


MI_HWDISPLAY?* 

Overrides DISPLAY. This is useful if mental ray is run on one machine, 
where all graphical user interfaces are shown (so DISPLAY must point 
to the local host), but the local host does not have sufficient hardware 
rendering capacity so mental ray offloads it to another host, pointed 
to by MI_HWDISPLAY. This kind of remote hardware rendering incurs 
extra networking overhead but allows multiple desktop clients to share 
a fast hardware rendering server. It is not necessary for mental ray to be 
installed on the server, and no extra license is used. However, both the 
client and server hosts must have compatible OpenGL and OpenGL 
extension versions. 
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MI_IVRAY_OPTIONS 


MI_LIBRARY_PATH 


MI_LIGHTPROFILE_PATH 


SI_LOCATION 


MI_RAY_SUBSTITUTE 


MI_RAY_INCPATH 


MI_RAY_OPTIONS 


MI_RAY2_SERVICE 


MI_RAY_SERVICE 


MI_RAY_SWAPDIR>’? 


MI_RAY_SWAPLIMIT? 2 
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Extra options inserted by the Inventor version of mental ray. 


Another search path, used for link commands. The directories in this 
path are searched for shader libraries. 


A search path used for lightprofile commands. The directories in 
this path are searched for light profile files. 


The directory of the linktab.ini file, which is used by the 
Softimagel3D application for path mapping. 


An optional list of blank-separated substitution instructions, each in 
the form /search/replace/. Any other character besides / will also 
work, 


A colon-separated or semicolon-separated list of paths to search for 
files included with the $include command. 


Extra options that are inserted by mental ray before the options on the 
command line. This is commonly used for options such as -xcolor. 


The IP service that mental ray uses to contact slaves on other machines. 
The default is mi-ray2 for mental ray 2.x and mi-ray3 for mental ray 
3.x. On Unix, service names are defined in /etc/services or in the 
services NIS map. 


If the previous variable is not defined, this one is used instead. This 
makes mental ray 2.x compatible with mental ray 1.9 while allowing 
both to coexist on the same machine. The default is mi-ray. 


A swap directory where mental ray can put scene elements when it 
runs out of memory. This can be useful for large static scenes, where 
the scene file itself is large. mental ray generally swaps more efficiently 
than the operating system. 


The maximum number of bytes to write into the swap directory. A 
value of 0 turns off swapping. 
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MI_ROOT 
The directory that mental ray searches for configuration files such as 
rayre. 


MI_STACKSIZE 
New thread stacks will be created with this size in kilobytes if defined. 
The default is 16384 (16 MB) on Unix and 4096 on Windows NT. 4096 
is nearly always sufficient except when very complex recursive shaders 
are used. 


MI_TEXTURE_PATH 
A search path used for texture commands. The directories in this 
path are searched for texture images. 


TMPDIR 
A directory for temporary code or object files to be compiled or 
linked. The default is /usr/tmp on Unix and the current directory on 
Windows NT. 

USER 


The current user name. It is stored in RLA image file headers, and is 
optional. 


Registry lookups of the form {$var} return the value of the environment variable var. mental 
ray 3.4 allows {$?var}, which returns 1 if the environment variable var exists and 0 otherwise. 


A.4 Image Display: imf_disp 


The image display and flipbook utility imf_disp is started as 
imf_disp [options] [directory] [file ...] 


If the directory is present, imf _disp will enter flipbook mode and display a sequence of files as a 
movie. If no directory is specified, a static image file is displayed. If a single minus sign is given 
as file name, the image will be read from standard input. This is useful for connecting mental ray 
and imf_disp: 


ray -imgpipe 1 scene.mi | imf_disp - 


If the file to display is still being rendered, imf_disp will open a connection to the mental ray 
program rendering it, and display rectangles as they are finished. This also works if mental ray 
and imf_disp run on different machines. Files that are still being rendered can be recognized by 
their size, which is always 128 bytes. Only one imf_disp can be connected to a running mental 
ray at any time. 
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The following options are supported on Unix systems. Many can also be set from pulldown 
menus. The standard X11 options such as -display or -geometry are also supported. The 
Windows NT version can only display static images and supports only the -g (gamma) option. 


-delaymultiplier factor 
Set timescale multiplier for flipbook playback speed. The default is 1.0. 


-depth min max 
When displaying depth (Z) images such as shadow maps, assign white to the 
minimum depth mun and black to the maximum depth max, instead of determining 
the range from the depth map’. Infinite depths are always displayed light blue. 


-G gamma 
Set a gamma value. The default is 1.0, or whatever mental ray is using if imf_disp 
is connected to one. 


-help 
Print a brief option summary. 


-imgtitle title 
Set the window title. Normally the window title displays information about the 
image file, the operation mode, and the pixel under the mouse. 


-m on|off 
Display the matte (alpha) channel instead of the color image. 


“mask exp 
Set the file search mask in the file selector dialog to the expression exp. The default 
is *. This dialog is used to select files to cycle through in flipbook mode. The mask 
is useful to restrict the file listing to similar-named files that are part of a sequence, 
such as image*.rgb. Note that exp should be quoted to prevent the shell from 
evaluating wildcards. 


-pseudocolor onloff 
If on, imf disp uses a pseudocolor visual that relies on color mapping and dithering. 
If off, true colors are used. The default is off. 


-reconnect on|off 
If enabled, imf disp will watch the displayed file. If it is re-rendered, imf_disp will 
connect to the mental ray executable and show the changes as they are finished. If 
disabled, the displayed image will stay on the display even if rerendered. The default 


is On. 


-reload on|off 
This option is similar to the preceding, but checks whether the image was rewritten 
by means other than rerendering, and reloads it if so. 


>This option was introduced with mental ray 2.1.36. 
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-shm on|off 
Set X11 shared-memory mode. This allows the X11 display server to directly use 
the process memory of imf_disp. This reduces memory usage, but since shared 
memory is an optional X11 extension, some systems may not support it. Shared 
memory also cannot be used if the display (as defined by the DISPLAY environment 
variable or the X11 -display option) is not on the machine that imf_disp is running 
on. The default is on. 


-verbose on|off 
Enable or disable verbose messages. The default is off. 


-vis visual 
Set the visual ID for the display. X11 visuals determine display information such 
as the color mode, the number of bits per pixel, and so on. Use the X11 xdpyinfo 
command to determine the visuals supported by the X11 server. Note that visual 
must be a decimal number. The default is the best truecolor visual available. 


A.5 Image Copy: imf_copy 


The image copying and conversion utility imf_copy is started as 

imf_copy [options] infile outfile [outtype] 
The file infile will be copied to outfile. The outtype specifies the format of outfile. If no type is 
specified, the file name extension of outfile is used. See section 1.12 for a list of valid formats. The 
map format is especially valuable for creating memory-mappable texture images (see page 112 for 
details). These options are supported: 


oh Print a brief option summary. 


-p Create a pyramid texture, consisting of a sequence of progressively smaller versions 
of the same image in one file. This allows better texture anti-aliasing. See page 20. 


-V Verbose output prints messages showing what imf_copy is doing, and a version 
banner. 


-ggamma_ Perform gamma correction with the gamma factor gamma. The default is 1.0. 


-q quality »*'When writing to a JPEG file, set the quality factor to quality, in the range 1..100. 
The default is 75. 


-f filter >-2Useful only if the target format is .map. The filter value is stored in the texture. 
Memory-mapped texture files always override the filter value specified in the color 
texture statement or with mi_api_texture_set_filter. 
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-x N 


A.6 
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> When resampling a format to another with fewer bits per component, perform 
error diffusion instead of truncation. 


>! When writing to a memory-mapped .map file, use little-endian byte order. Map 
files must have the byte order of the rendering host to be effective. Alpha and 
x86-class processors including Intel Pentium are little-endian; most others are big- 
endian. 


>! When writing to a memory-mapped .map file, use big-endian byte order. 


>? When writing toa memory- mapped .map file, arrange pixels in rectangles instead 
of the normal scanline order. This increases cache efficiency and reduces memory 
usage when rendering. Files created in this way can only be rendered with mental 
ray 3.2 or higher, which is why it is not enabled by default. 


>?When writing to a memory- mapped .map file, collate up to 20 input files to form 
an image pyramid. This option gives control over the image pyramid, unlike the - 
p option which automatically creates each successive pyramid level at one-half the 
resolution of the preceding one, using a box filter. The first input image should have 
full resolution, the next one approximately one-half width and height, the next one 
approximately one quarter, and so on. Files created with this option can be read by 
any mental ray 3.x version. 


°-°Extract level N from a pyramid .map file. The first (and largest) level is 0; the 
highest is 19. This can be seen as the reverse operation to -c, but it also works with 
pyramids created with —p. 


°-4*When writing to an OpenEXR file, set the compression method to K, where K is 
one of the following: none, piz, zip, rle, pxr24. Default is rle. 


Image Information: imf_info 


The image information utility imf_info is started as 


imf_info [options] file... 


It will display information about all named image files, including resolution, number of color 
components, number of bits per component, gamma factor if available, top-down or bottom-up 
line ordering, data type, and the image format. There is only one option: 


—-V 


~P 


—m 


Verbose output prints messages showing what imf_info is doing, and a version 
banner. 


>-!Plot a simple pixel intensity histogram. 


>?Prints information about multipass sample files. 
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= >2Prints pyramid layer resolutions for memory-mapped texture files. 


ae °2Prints more detailed pyramid layer information, including deviations from the 
expected resolutions. This is useful for map files created with imf_copy ~c. 


A.7_ Image Comparison: imf_diff 


The image comparison utility imf_diff is started as 

imf_diff [options] imagel image2 [outimage |outtype]]| 
The files mage and image2 will be compared, and a comparison summary is printed. If outimage 
is specified, a difference image with a histogram is written to outimage. The file format of this file 
is specified with outtype if present, or taken from the file name extension if not. The following 
options are supported: 


-a Ignore alpha channel differences. 


-d Display the difference image and the histogram in a window, by starting the imf_ 
disp program. This works with and without an outimage on the command line. 


-e Write an output image even if the compared input images match. Normally the 
output image is written only if there are differences. 


= Show differences in false colors, ranging from irrelevant differences in blue, through 
significant differences in green, red, and white. 


-g gamma _ Perform gamma correction with the given gamma factor. 

=h Print a brief option summary. 

-m thresh Set the threshold in the range 0..255. Component differences less than this threshold 
are ignored. The default is 3. The main purpose is to discard differences introduced 
by dithering (mental ray’s dither option). 


—n Do not add a histogram to the displayed or saved output image. 


“5 Magnity the differences such that the largest difference is white and appears at the 
right edge of the histogram. 


-t thresh The difference in percent that causes imf_diff to return the return code 1 instead 
of 0. The default is 1. This is useful for automated test suites. 


-u Underlay image1 under the displayed or saved difference image, at 1/10th 
brightness. This helps locating differences. 
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-v Verbose output prints messages showing what imf_copy is doing, and a version 
banner. 


The most common options are -f -u ~-d (also known as fear, uncertainty, and doubt). Note that 
the sampling nature of mental ray means that the true image is approximated with appropriately 
selected samples until the desired image quality criteria are satisfied. This approach ensures 
consistent quality but it does not necessarily create images that are bit-for-bit identical if rendered 
under different circumstances, such as different image task sizes, image task assignments to threads 
or machines, different machines or different networks, or different sampling options. Typically, 
differences shown in blue in the color histogram are irrelevant. 


A.8 Create Shader Skeletons: mkmishader ** 


The shader skeleton utility mkmishader is started as 
mkmishader [options] [scenefile...] 


This utility is intended for shader writers only. It takes shader declaration files and generates C 
source code files that implement the shader. The scenefiles should only contain shader declarations. 
One source file per shader is created. If it already exists, it is overwritten. The sources include 
all necessary includes, declarations, local variables, parameter evaluation statements, and array 
loops, but the implementation of the actual algorithm is, of course, missing. The body of the 
shader function usually needs to be rearranged, the local variables, evaluations, and loops are 
created in no particular order. The following options are supported: 


-h Print a brief option summary. 
=i Also create init and exit shaders. 
-r Read the startup .rayrc file first. This is not done by default because startup files 


sometimes contain shader declarations, which would cause mkmishader to generate 
source code. 


~e Verbose output prints messages showing what mkmishader is doing, and a version 


banner. 


A.g Convert Scenes to C: mitoapi ** 


The API call generator utility mitoapi is started as 
mitoapi scenefile 


This utility is intended for writers of geometry shaders, and for integrators of the mental ray 
library into client applications. It reads a scene file and generates the corresponding C API calls 
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that do the same thing. The resulting source code is an approximation that can not be compiled 
directly and needs manual rearrangement. In particular, local variables are not distinguished and 
are listed in the order of recursive descent during scene parsing. However, the resulting source 
code is a good starting point for implementation. There are no options. 


A.10 Finalgather Map Copy: fg_copy ** 


The finalgather map copying and merging utility £g_copy is started as 
fg_copy [options] infilel ... infileN outfile 


It reads finalgather map files znfile* created with finalgather file statements in the options 
block in the .mi scene file, and merges them into a single finalgather file outfile. Each file is a 
collection of finalgather points that represent the irradiance at a specific 3D coordinate. 


Optionally, only points in a given region are considered and written. Points that are very close 
and have similar orientation can optionally be merged to eliminate redundancy and reduce the 
size of the generated map. 


This tool is helpful when rendering animations. Flickering is reduced with moderate com- 
putational effort if several key frames are rendered with final gathering saved to files. The 
-finalgather only command-line option of mental ray option allows rendering these files 
quickly without rendering color images. When all the finalgather map files for the key frames are 
finished, the fg_copy tool can combine them into a single finalgather map file that can be used for 
beauty-rendering the entire animation. (This does not work for detail shadowmaps?” files.) 


This method works well with render farms, where different hosts create finalgather maps for 
different frames simultaneously. 


If the same file is specified several times as an input file, its points appear multiple times in the 
output map. If point merging is enabled, the points are not duplicated but their importance 
weights are adjusted. 


The following options are supported: 
-h Print a brief option summary. 


=f F Merge finalgather points with similar normals within distance F into a single one. 
The value of F is related to the minimum radius of the finalgather accuracy 
statement in the .mi scene file. All finalgather points are tested against all other 
finalgather points regardless of which file they came from. In particular, fg-_copy can 
be used to reduce the redundancy and size of a single input file. 


-b xmin ymin zmin xmax ymax zmMax 
Select and copy finalgather points within the specified voxel only. This may be used 
for reducing the finalgather map size if only a part of the scene is required. 
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-v Verbose output prints messages showing what fg_copy is doing, and a version 
banner. 


Note that the finalgather file statement in the options block of the .mi scene file also allows 
specifying multiple finalgather map files, enclosed in angle brackets, which will be merged at 
render time. Using fg_copy to precompute a merged map for a list of keyframes for the entire 
animation is more efficient. 


Appendix B 


Scene File Grammar 


This appendix contains the formal syntax of the mental images .mi scene description format. The 
grammar is in yacc format; yacc is a Unix compiler generator. Nonterminals that begin with T_ 


are typed values: 


T_SYMBOL 


T_INTEGER 


TFLOAT 


T_STRING 


T_BYTE_STRING 


T_VECTOR 


is an unquoted string consisting of zero or more letters, numbers, and 
underscores and does not begin with a number. 


is anonempty sequence of numerical digits. 


is a nonempty sequence of digits, followed by a period, followed by a 
nonempty sequence of digits. 


is a sequence of arbitrary printable characters enclosed in double quotes. 
Nonprintables such as newlines are not allowed. Backslash and double quote 
characters that should be part of the string must be prefixed with a backslash. 


is a sequence of hexadecimal bytes, each consisting of two characters in the 
range 0..9 or a..f. Line breaks are allowed between bytes. Other characters 
are not allowed. The maximum length is 1024 bytes (2048 characters); for 
more bytes use multiple strings. 


is a backquote followed by 12 bytes followed by a backquote. The 12 bytes 
are the binary image of three floats in big-endian order. 


This appendix is intended to aid translator writers, and to describe the relationship between the 
.mi scene description language and the API available to geometry shader writers. This is the 
complete mental ray 3.4 grammar. 
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Astart 


Zunion 


} 


token 
Atoken 
token 
Atoken 
Atoken 
Atoken 


Atoken 
token 
token 
Atoken 
Atoken 
Atoken 
token 
Atoken 
Atoken 
Atoken 
Atoken 
Ztoken 
Atoken 
Atoken 
/Z,token 
token 
token 
Atoken 
token 
token 
/,token 
Z,token 
Atoken 
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start 
i 

miBoolean boolean; 
char *symbol ; 

char *string; 
struct { 

int len; 
miUchar *bytes; 

} byte_string; 
int integer ; 
double floating; 
float floatoctet [8]; 
miMatrix matrix; 
miColor color; 
miVector vector; 
miGeoVector geovector; 
miTransform *transform; 
miParameter *para_type; 
miDlist *dlist; 
miTag tag; 
<symbol> T_SYMBOL 
<integer> T_INTEGER 
<floating> T_FLOAT 
<string> T_STRING 
<byte_string> T_BYTE_STRING 
<vector> T_VECTOR 


ACCELERATION ACCURACY ADAPTIVE ALL ALPHA ANGLE ANY APERTURE APPLY 
APPROXIMATE ARRAY ASPECT AUTOVOLUME 

B BACK BASIS BEZIER BIAS BLUE BOOLEAN BORDER BOTH BOX BSDF BSP 

BSPLINE BUFFER BUMP 

CALL CAMERA CARDINAL CAUSTIC CG CHILD 

CLASSIFICATION CLIP CODE COLLECT COLOR COLORCLIP COLORPROFILE 

COMPRESS CONE 

CONIC CONNECT CONSTANT CONTOUR CONTRAST CONTROL CORNER CP CREASE 
CURVATURE CURVE CUSP CYLINDER 

D D2 DART DATA DEBUG_ DECLARE DEFAULT DEGREE DELAUNAY DELETE_ DENSITY 
DEPTH DERIVATIVE DESATURATE DETAIL DIAGNOSTIC DIRECTION DISC DISPLACE 
DISTANCE DITHER DOD DOF DPI 

ECHO EMITTER END ENVIRONMENT EVEN ENERGY EULUMDAT EXPONENT 

FACE FALLOFF FALSE_ FAN FAST FASTLOOKUP FIELD FILE_ FILTER FINALGATHER 
FINE FLAGS FOCAL FORCE FORMAT FRAGMENT FRAME FREEZE FRONT 

GAMMA GAUSS GEOMETRY GLOBILLUM GRADING GREEN GRID GROUP GUI 

HAIR HARDWARE HERMITE HIDE HOLE 

IES IMP IMPLICIT INCREMENTAL INFINITY_ INHERITANCE INSTANCE INSTGROUP 
INTEGER INTERFACE_ IRRADIANCE 

JITTER 

LANCZOS LARGE LENGTH LENS LEVEL LIGHT LIGHTMAP LIGHTPROFILE LINK LOCAL 
LUMINANCE 

M MAPSTO MASK MATERIAL MATRIX MAX_ MEMORY MERGE MI MIN_ MITCHELL MIXED 
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ZAtoken MOTION 

Atoken N NAMESPACE NATIVE NOCONTOUR NOSMOOTHING NORMAL NULL_ NTSC 

Atoken OBJECT ODD OFF OFFSET OFFSCREEN ON ONLY OPAQUE_ OPENGL OPTIONS ORIGIN 
Ztoken OUTPUT OVERRIDE 

Atoken P PARALLEL_ PARAMETRIC PASS PHENOMENON PHOTON PHOTONMAP PHOTONS 
Z,token PHOTONVOL POLYGON POSITION PREMULTIPLY PREP PRESAMPLE PRIORITY PRIVATE 
Ztoken PROTOCOL 

Atoken QUALITY 

%token RADIUS RAPID RATIONAL RAY RAYCL RAW READ REBUILD RECTANGLE RECURSIVE 
%Atoken RED REFLECTION REFRACTION REGISTRY REGULAR 

%Atoken RENDER RESOLUTION RGB_ ROOT 

Atoken SAMPLELOCK SAMPLES SCALE SCALAR SCANLINE SEGMENTS SELECT SESSION SET 
Atoken SHADER SHADING SHADOW SHADOWMAP SHARP SHUTTER SIZE SOFTNESS SORT SPACE 
%token SPATIAL SPDL SPECIAL SPECTRUM SPHERE SPREAD STATE STEPS STORE STRING 
%Atoken STRIP STRUCT 

%token SUBDIVISION SURFACE SYSTEM 

*%token T TAG TAGGED TASK TAYLOR TEXTURE TIME TRACE TRANSFORM TRAVERSAL 
%Atoken TOPOLOGY TOUCH 

Atoken TRANSPARENCY TREE TRIANGLE TRILIST TRIM TRUE_ 

%Atoken U UNIFORM USER 

%Ztoken V VALUE VECTOR VENDOR VERBOSE VERSION VERTEX VIEW VISIBLE VOLUME 
%token W WEIGHT WHITE WIDTH WINDOW WORLD WRITABLE WRITE 


Atype <floating> floating 

Atype <boolean> boolean 

Atype <string> symbol 

Atype <string> opt_symbol 
Atype <matrix> transform 
Atype <integer> tex_flags 
Atype <integer> tex_flag 

Atype <integer> tex_type 

type <integer> simple_type 
Atype <string> inst_item 
itype <tag> inst_func 
Atype <tag> inst_params 
type <tag> function 

type <tag> function_list 
type <tag> tex_func_list 
itype <tag> phen_root 
type <para_type> shret_type 
type <para_type> shret_type_nosh 
Atype <para_type> shret_decl_seq 
type <para_type> shret_decl 
Atype <para_type> decl_simple 
Atype <para_type> parm_decl_list 
type <para_type> parm_decl_seq 
itype <para_type> parm_decl 
/type <vector> vector 

Atype <integer> apply 

Atype <integer> apply_list 
Atype <integer> filter_type 
Atype <string> colorspace_set 


type <tag> opt_function_list 
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Atype <string> opt_string 
Atype <integer> colorclip_mode 
type <geovector> geovector 
type <color> color 
Atype <string> mtl_or_label 
type <boolean> rational 
type <dlist> basis_matrix 
htype <floating> merge_option 
htype <dlist> para_list 
type <boolean> opt_volume_flag 
type <boolean> opt_vector_flag 
type <boolean> opt_incremental 
type <floatoctet> out_parms 
Atype <integer> c_filter_type 
Atype <integer> pass_samples 
htype <dlist> string_list 
Atype <dlist> map_list 
Atype <integer> opt_size 
type <integer> pl_border 
hh 
start 
{ functag = 0; 
mi_api_incremental(is_incremental = miFALSE) ; 
mi_api_private(session_depth = 0); 
my_timer = mi_timing(0, 0); } 
command_list 
{ mi_timing(my_timer, 0); } 
| 
/*------------------------- --- - ee 
* primitive types 
*#------------------------------------------- -- -- - - - - - - - - - $5 = * / 
boolean ON 
{ $$ = miTRUE; } 
| OFF 
{ $$ = miFALSE; } 
| TRUE_ 
{ $$ = miTRUE; } 
| FALSE_ 
{ $$ = miFALSE; } 
floating : TWFLOAT { $$ = $1; } 
| T_INTEGER { $$ = $1; } 
vector : floating floating floating 


{ $$.x = $1; $$.y = $2; $$.z 


$3; } 
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geovector 


color 


transform 


symbol 


opt_symbol 


opt_string 


colorclip_mode 


T_VECTOR 
{ $$ = $1; } 


: floating floating floating 


{ $$.x = 
T_VECTOR 
{ $$.z = 


: floating floating floating 


: TRANSFORM 


{ $$.r = 


$1; $$.y = $2; $$.z 


$1.z; $$.y = $1.y; $$.x = 


$1; $$.g = $2; $$.b = $3; 


= $25 2 


floating floating floating floating 


{ $$.r = 


{ $$L0] 
$$ [4] 
$$ [8] 


$2; $$([1] 
$6; $$([5] 
$10; $$[9] 


$$[12]= $14; $$[13]= $15; $$[14]= $16; $$[1i5]= $17; } 


: T_SYMBOL 
{ $$ = $1; } 
T_STRING 
{ $$ = $1; } 
{ $$ = 0; } 
symbol 
{ $$ = $1; } 
{ $$ = 0; } 
T_STRING 
{ $$ = $1; } 
RGB_ 


$1; $$.g = $2; $$.b = $3; 


floating floating floating 
floating floating floating 
floating floating floating 
floating floating floating 


$3 ; 


= $7; 
$11; $$(10]= $12; $$[11] 


$$(2] = $4; 
$$L6] = $8; 


{ $$ = miIMG_COLORCLIP_RGB; } 


ALPHA 


{ $$ = miIMG_COLORCLIP_ALPHA; } 


RAW 


{ $$ = miIMG_COLORCLIP_RAW; } 


$$.a 


$$.a 


$1.7 } 


1.0£; } 


$4; } 


floating 
floating 
floating 
floating 


$$ [3] 
$$ [7] 


$5; 
$9; 
$13; 
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command_list 


command 


A 


command 


command _ 


{ 


command 


set 
frame 
debug 
cals 
version 
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mi_api_incremental(is_incremental = miFALSE) ; 
mi_api_private(session_depth = 0); } 


list 
mi_api_incremental(is_incremental = miFALSE) ; 
mi_api_private(session_depth = 0); } 


incr_command 


PRIVATE 
{ 


mi_api_private(session_depth = 255); } 


incr_command 


SESSION 


DEPTH T_INTEGER 


{ mi_api_private(session_depth = $3); } 
incr_command 
INCREMENTAL 

{ mi_api_incremental(is_incremental = miTRUE) ; 


mi_api_private(session_depth = 0); } 


incr_command 


DELETE_ 
{ 


symbol 
mi_api_delete($2); } 


RENDER symbol symbol symbol 


{ 


VERBOSE 
sf 


VERBOSE 
{ 


mi_timing(my_timer, "mi scene file parsing") ; 
mi_timing(my_timer, 0); 
mi_api_render($2, $3, $4, 
mi_mem_strdup(ctx->inheritance_func)) ; 
yyreturn MIYYRENDER; } 
boolean 
if (!ctx->mi_force_verbose) 
mi_set_verbosity($2? miERR_ALL & ~miERR_DEBUG 
& ~miERR_VDEBUG 
: miERR_FATAL|miERR_ERROR) ; } 
T_INTEGER 
if (!ctx->mi_force_verbose) 
mi_set_verbosity((1 << $2) - 1); } 


ECHO T_STRING 


| 


mi_info("%s", $2): 
mi_mem_release($2); } 


SYSTEM T_STRING 


{ 


if ((system($2) >> 8) & Oxff) 
mi_api_warning("system \"%s\" failed", $2); 
mi_mem_release($2); } 
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| MEMORY T_INTEGER 
{ mi_api_warning("memory view parameter ignored"); } 
| CODE T_STRING 
{ mi_link_file_add($2, miTRUE, miFALSE, miFALSE) ; 
mi_mem_release($2); } 
| CODE 
{ mi_api_code_verbatim_begin(); } 
code_bytes_list 
{ mi_api_code_verbatim_end(); } 
| LINK T_STRING 
{ mi_link_file_add($2, miFALSE, miFALSE, miFALSE) ; 
mi_mem_release($2); } 
DECLARE function_decl 
DECLARE phenomenon_decl 
DECLARE data_decl 
REGISTRY symbol 
{ mi_api_registry_begin($2); } 
reg_body END REGISTRY 
{ mi_api_registry_end(); } 
| TOUCH symbol 
{ mi_api_touch($2); } 
| NAMESPACE symbol 
{ mi_api_scope_begin($2); } 
| END NAMESPACE 
{ mi_api_scope_end(); } 


reg_body 
| reg_item reg_body 
reg_item : VALUE symbol 
{ mi_api_registry_add(mi_mem_strdup("value"), $2); } 
| LINK symbol 
{ mi_api_registry_add(mi_mem_strdup("link"), $2); } 
| CODE symbol 
{ mi_api_registry_add(mi_mem_strdup("code"), $2); } 
| MI symbol 
{ mi_api_registry_add(mi_mem_strdup("mi"), $2); } 
| SPDL symbol 
{ mi_api_registry_add(mi_mem_strdup("spd1"), $2); } 
| ECHO symbol 
{ mi_api_registry_add(mi_mem_strdup("echo"), $2); } 
| SYSTEM symbol 
{ mi_api_registry_add(mi_mem_strdup("system"), $2); } 
| symbol symbol 
{ mi_api_registry_add($1, $2); } 
incr_command : light 
| instance 
| options 


| camera 
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object 

texture 

profile_data 

cprof 

spectrum_data 

material 

instgroup 

userdata 

gui 

SHADER symbol function_list 
{ mi_api_shader_add($2, $3); } 


code_bytes_list : T_BYTE_STRING 
{ mi_api_code_byte_copy($1.len, $1.bytes); } 
| code_bytes_list T_BYTE_STRING 
{ mi_api_code_byte_copy($2.len, $2.bytes); } 


set : SET symbol 
{ mi_api_variable_set($2, 0); } 
| SET symbol symbol 
{ mi_api_variable_set($2, $3); } 


call : CALL function_list 
{ mi_api_shader_call($2, 0, 0); } 
| CALL function_list ’,’ symbol symbol 


{ mi_api_shader_call($2, $4, $5); } 


debug : DEBUG_ symbol opt_symbol 
{ mi_api_debug($2, $3); } 


version : VERSION T_STRING 
{ mi_api_version_check($2, 0); } 
| MIN_ VERSION T_STRING 
{ mi_api_version_check($3, 0); } 
| MAX_ VERSION T_STRING 
{ mi_api_version_check($3, 1); } 


PCC OOOO I I Ia IK a aK Ca 2 2k 2k 2k 3k 6 24 2k 2k 9 2 24 2k ak 
2 KK KK KK OK RK AK KK A KK OK AK KK OK mii compatibility EK OK KK KK KOK KOK a KOK Ok 
FARR I I I I a a a aK a ak 3 9 9 6 2k 2k 2k 2k 2k 2k 2k 9 9 5 2 2k 2k ak ok ok ok ok 2 2 ak kk ak ak ak / 
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{ mi_api_frame_begin(&camera, &options); } 
frame_number 
initial_frame_cmd_list 
view 
frame_command_list 
END FRAME 
{ mi_timing(my_timer, "mi scene file parsing"); 
mi_timing(my_timer, 0); 
mi_api_frame_end() ; 
yyreturn MIYYENDFRAME; } 


initial _frame_cmd_list 


| initial_frame_cmd_list initial_frame_cmd 


> 


initial_frame_cmd 
: texture 
| light 
| material 


frame_command_list 


| frame_command_list frame_command 


. 
’ 


frame_command 

; texture 
| light 
| material 
| object 
| call 
| debug 
| version 
| gui 


view : VIEW 
{ have_l = have_o = have_v = have_e = have_p = 0; } 
view_list 
END VIEW 


view_list 
view_list view_item 
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view_item 
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camview_item 
optview_item 
MIN_ SAMPLES T_INTEGER 


{ options->min_samples = $3; } 
MAX_ SAMPLES T_INTEGER 
{ options->max_samples = $3; } 


SAMPLES T_INTEGER 
{ mi_api_warning ( 
"\"samples\" view parameter ignored"); } 
RECURSIVE boolean 
{ if (!$2) 
mi_api_warning("\"recursive off\" ignored"); } 
ADAPTIVE boolean 
{ mi_api_warning("\"adaptive\" statement ignored"); } 
ACCELERATION RAY CLASSIFICATION 
{ options->acceleration = ’b’; 
mi_api_warning( 
"ray classification is obsolete, using BSP"); } 
ACCELERATION SPATIAL SUBDIVISION 


{ options->acceleration = ’b’; } 
ACCELERATION GRID 
{ options->acceleration = ’g’; } 


SUBDIVISION MEMORY T_INTEGER 

{ mi_api_warning("ray classification is obsolete, " 

"statement \"subdivision memory %d\" ignored", $3); } 

SUBDIVISION T_INTEGER T_INTEGER 

{ mi_api_warning("ray classification is obsolete, " 

"statement \"subdivision 4d %d\" ignored", $2, $3); } 

MAX_ SIZE T_INTEGER 

{ options->space_max_size = $3; } 
MAX_ DEPTH T_INTEGER 

{ options->space_max_depth = $3; } 
SHADOW SORT boolean 

{ if ($3) options->shadow 
SHADOW SEGMENTS boolean 

{ if ($3) options->shadow = ’s’; } 
transform 

{ mi_api_view_transform($1); } 
RED floating floating 
GREEN floating floating 
BLUE floating floating 
WHITE floating floating 


st } 


DOO O R KK « 


RO I KK KK new mi2 features OO ARK 
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options 


option_list 


option_item 


: OPTIONS symbol 


{ options = mi_api_options_begin($2) ; 
have_pm = miFALSE; 
have_sf = 0; } 
option_list END OPTIONS 
{ mi_api_options_end(); } 


option_list option_item 


optview_item 
{ curr_datatag = koptions->userdata; } 
data 
ACCELERATION RAYCL 
{ options->acceleration = ’b’; 
mi_api_warning ( 


"ray classification is obsolete, using BSP"); } 


ACCELERATION BSP 


{ options->acceleration = ’b’; } 
ACCELERATION LARGE BSP 

{ options->acceleration = ’1’; } 
ACCELERATION OBJECT BSP 

{ options->acceleration = ’B’; } 


ACCELERATION GRID 
{ options->acceleration = ’g’; } 
MOTION boolean 
{ if ($2) options->motion = 1; } 
MOTION STEPS T_INTEGER 
{ options->n_motion_vectors = $3;} 
DIAGNOSTIC SAMPLES boolean 
{ miBIT_SWITCH (options->diagnostic_mode, 
miSCENE_DIAG_SAMPLES , $3) ; } 
DIAGNOSTIC PHOTON OFF 
{ miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_PHOTON, miFALSE) ; } 
DIAGNOSTIC PHOTON DENSITY floating 
{ miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_PHOTON, miFALSE) ; 
miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_PHOTON_D, miTRUE) ; 
options->diag_photon_density = $4;} 
DIAGNOSTIC PHOTON IRRADIANCE floating 
{ miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_PHOTON, miFALSE) ; 
miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_PHOTON_I, miTRUE) ; 
options->diag_photon_density = $4;} 
DIAGNOSTIC GRID OFF 
{ miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_GRID, miFALSE) ;} 
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DIAGNOSTIC GRID OBJECT floating 
{ options->diag_grid_size = $4; 
miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_GRID, miFALSE) ; 
miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_GRID_O, $4 != 0.0);} 
DIAGNOSTIC GRID WORLD floating 
{ options->diag_grid_size = $4; 
miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_GRID, miFALSE) ; 
miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_GRID_W, $4 != 0.0);} 
DIAGNOSTIC GRID CAMERA floating 
{ options->diag_grid_size = $4; 
miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_GRID, miFALSE) ; 
miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_GRID_C, $4 != 0.0);} 
DIAGNOSTIC BSP OFF 
{ miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_BSP, miFALSE); } 
DIAGNOSTIC BSP DEPTH 
{ miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_BSP_D, miTRUE); } 
DIAGNOSTIC BSP SIZE 
{ miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_BSP_L, miTRUE); } 
DIAGNOSTIC FINALGATHER boolean 
{ miBIT_SWITCH(options->diagnostic_mode, 
miSCENE_DIAG_FG, $3) ;} 
SAMPLES T_INTEGER 


{ options->min_samples = $2-2; 
options->max_samples = $2; } 
SAMPLES T_INTEGER T_INTEGER 
{ options->min_samples = $2; 


options->max_samples = $3; } 
SAMPLES T_INTEGER T_INTEGER T_INTEGER T_INTEGER 
{ options->min_samples = $2; 
options->max_samples = $3; 
options->def_min_samples = $4; 
options->def_max_samples = $5; } 
SAMPLES COLLECT T_INTEGER 
{ if ($3 > 0) 
options->rapid_collect_rate = $3; 
else if ($3 < 0) 
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mi_warning("invalid negative \"samples" 
"collect %d\" has been ignored.", 


$3) ; 
} 
SAMPLES MOTION T_INTEGER 
{ options->rapid_motion_resample = $3; } 
SHADOW SORT 
{ options->shadow = ’1’; } 
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optview_item 


SHADOW SEGMENTS 
+. options->shadow = ’s’; } 
COLORPROFILE symbol 


{ options->render_cprof = mi_api_name_lookup($2); } 


COLORPROFILE symbol WHITE symbol 
{ options->render_cprof = mi_api_name_lookup($2) ; 


options->white_cprof = mi_api_name_lookup($4); } 


: SHADOW OFF 


{ options->shadow = 0; } 
SHADOW ON 

{ options->shadow 
TRACE boolean 

{ options->trace = $2; } 
SCANLINE boolean 

{ options->scanline 
SCANLINE RAPID 

{ options->scanline 
SCANLINE OPENGL 

{ options->scanline 
LENS boolean 

{ options->no_lens = !$2; } 
VOLUME boolean 

{ options->no_volume = !$2; } 
GEOMETRY boolean 

{ options->no_geometry 
DISPLACE boolean 

{ options->no_displace = !$2; } 
DISPLACE PRESAMPLE boolean 

{ options->no_predisplace = !$3; } 
OUTPUT boolean 

{ options->no_output = !$2; } 
MERGE boolean 

{ options->no_merge = !$2; } 
HAIR boolean 


Il 
= 
Le 


$2; } 


T 
H 
WY 


rT 
° 
WY 


'$2; } 


{ options->no_hair = !$2; } 
PASS boolean 
{ options->no_pass = !$2; } 


AUTOVOLUME boolean 
{ options->autovolume = $2; } 
PHOTON AUTOVOLUME boolean 
{ options->photon_autovolume = $3; } 
FILTER filter_type 
{ options->filter = $2; 
options->filter_size_x = 


options->filter_size_y = 0.0; } 
FILTER filter_type floating 
{ options->filter = $2; 
options->filter_size_x = 
options->filter_size_y = $3; } 


FILTER filter_type floating floating 
{ options->filter = $2; 
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options->filter_size_x = $3; 
options->filter_size_y = $4; } 
FACE FRONT 
{ options->face = ’f’; } 
FACE BACK 
{ options->face = ’b’; } 
FACE BOTH 
{ options->face 
FIELD OFF 
{ options->field 
FIELD EVEN 
{ options->field 
FIELD ODD 
{ options->field = ’o’; } 
SAMPLELOCK boolean 
{ options->samplelock = $2; } 
PHOTON TRACE DEPTH T_INTEGER 


ll 
I ll 
v oO re) 
oO we ~ 
vs = 
W 
bel 


{ options->photon_reflection_depth = $4; 
options->photon_refraction_depth = $4; 
options->photon_trace_depth = $4 + $4; } 


PHOTON TRACE DEPTH T_INTEGER T_INTEGER 
{ options->photon_reflection_depth = $4; 
options->photon_refraction_depth = $5; 
options->photon_trace_depth = $4 + $5; } 
| PHOTON TRACE DEPTH T_INTEGER T_INTEGER T_INTEGER 
{ options->photon_reflection_depth = $4; 
options->photon_refraction_depth = $5; 
options->photon_trace_depth $6; } 
| FINALGATHER TRACE DEPTH T_INTEGER 
{ options->fg_reflection_depth = 
options->fg_refraction_depth 
options->fg_diffuse_depth 
options->fg_trace_depth = $4 + $4; } 
| FINALGATHER TRACE DEPTH T_INTEGER T_INTEGER 
{ options->fg_reflection_depth = $4; 
options->fg_refraction_depth = $5; 
options->fg_diffuse_depth = 
options->fg_trace_depth = $4 + $5; } 
FINALGATHER TRACE DEPTH T_INTEGER T_INTEGER T_INTEGER 
{ options->fg_reflection_depth = $4; 
options->fg_refraction_depth = $5; 
options->fg_diffuse_depth = 
options->fg_trace_depth = $6; } 
FINALGATHER TRACE DEPTH T_INTEGER T_INTEGER 
T_INTEGER T_INTEGER 
{ options->fg_reflection_depth = $4; 
options->fg_refraction_depth = $5; 
options->fg_diffuse_depth = $6; 


$4; 


options->fg_trace_depth = $7; } 
| TRACE DEPTH T_INTEGER 
{ options->reflection_depth = $3; 
options->refraction_depth = $3; 
options->trace_depth = $3 + $3; } 
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TRACE DEPTH T_INTEGER T_INTEGER 
{ options->reflection_depth = $3; 
options->refraction_depth = $4; 
options->trace_depth = $3 + $4; } 
TRACE DEPTH T_INTEGER T_INTEGER T_INTEGER 
{ options->reflection_depth = $3; 
options->refraction_depth = $4; 
options->trace_depth = $5; } 
CONTRAST floating floating floating 
{ options->contrast.r = $2; 
options->contrast.g = $3; 
options->contrast.b = $4; 
options->contrast.a = ($2 + $3 + $4)/3; } 
CONTRAST floating floating floating floating 
{ options->contrast.r = $2; 
options->contrast.g = $3; 
options->contrast.b = $4; 
options->contrast.a = $5; } 
TIME CONTRAST floating floating floating 
{ options->time_contrast.r oo. 
options->time_contrast.g = $4; 
options->time_contrast.b = $5; 
options->time_contrast.a = ($3 + $4 + $5)/3; } 
TIME CONTRAST floating floating floating floating 
{ options->time_contrast.r = $3; 
options->time_contrast.g = $4; 
options->time_contrast.b = $5; 
options->time_contrast.a = $6; } 
CONTOUR STORE function 
{ options->contour_store = $3; } 
CONTOUR CONTRAST function 
{ options->contour_contrast = $3; } 
STATE 
{ mi_api_function_delete(xoptions->state_func) ; 
have_sf = 0; } 
STATE function_list 
{ if (!have_sf++) 
mi_api_function_delete (&options->state_func) ; 
options->state_func = mi_api_function_append( 
options->state_func, $2); } 


JITTER floating 


{ options->jitter = $2; } 
SHUTTER floating 
{ options->shutter = $2; 
options->motion = options->shutter > 0; } 


SHUTTER floating floating 
{ options->shutter_delay = $2; 
options->shutter = $3; 
options->motion = options->shutter > 0; } 
TASK SIZE T_INTEGER 
{ options->task_size = $3; } 
RAYCL SUBDIVISION T_INTEGER T_INTEGER 
{ mi_api_warning("ray classification is obsolete, " 
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"statement \"raycl subdivision %d %d\" ignored", 


$3, $4); } 


RAYCL MEMORY T_INTEGER 
{ mi_api_warning("ray classification is obsolete, " 
"statement \"raycl memory /d\" ignored", $3); } 
| BSP SIZE T_INTEGER 
{ options->space_max_size = $3; } 
BSP DEPTH T_INTEGER 
{ options->space_max_depth = $3; } 
BSP MEMORY T_INTEGER 
{ options->space_max_mem = $3; } 
BSP SHADOW boolean 
{ options->space_shadow_separate = $3; } 
GRID SIZE T_INTEGER 
{ options->grid_max_size = $3; } 
GRID SIZE T_FLOAT 
{ options->grid_res[0] = 
options->grid_res[1] 
options->grid_res[2] = $3; 
mi_api_warning("obsolete grid size statement, 
"use grid resolution instead"); } 
GRID RESOLUTION T_INTEGER 
{ options->grid_res[0] = 
options->grid_res [1] 
options->grid_res[2] = $3; } 
GRID RESOLUTION T_INTEGER T_INTEGER T_INTEGER 
{ options->grid_res[0] = $3; 
options->grid_res[1] = $4; 
options->grid_res[2] = $5; } 
GRID DEPTH T_INTEGER 
{ options->grid_max_depth = $3; } 
DESATURATE boolean 
{ options->desaturate = $2; } 
| DITHER boolean 
{ options->dither = $2; } 
PREMULTIPLY boolean 


{ options->nopremult = !$2; } 
| COLORCLIP colorclip_mode 
{ options->colorclip = $2; } 


| GAMMA floating 
{ options->gamma = $2; } 
OBJECT SPACE 


{ options->render_space = ’o’; } 
| CAMERA SPACE 

{ options->render_space = ’c’; } 
| MIXED SPACE 

{ options->render_space = ’m’; } 


WORLD SPACE 
{ mi_api_warning ( 
"world space statement ignored"); } /*<<<x*/ 
INHERITANCE symbol 
{ options->inh_is_traversal = miFALSE; 
if (ctx->inheritance_func) 
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mi_mem_release(ctx->inheritance_func) ; 
ctx->inheritance_func = $2; 
if (!(options->inh_funcdecl = mi_api_decl_lookup( 
mi_mem_strdup ($2) ))) 
mi_api_nerror(176, "undeclared inheritance " 
“shader \"Ze\"", $2): 
} 
| TRAVERSAL symbol 
{ options->inh_is_traversal = miTRUE; 
if (ctx->inheritance_func) 
mi_mem_release(ctx->inheritance_func) ; 
ctx->inheritance_func = $2; 
if (!(options->inh_funcdecl = mi_api_decl_lookup( 
mi_mem_strdup ($2) ))) 
mi_api_nerror(177, "undeclared traversal " 
“shader \",e\"", $2); 
} 
| SHADING SAMPLES floating 
{ options->rapid_shading_samples = $3; } 
| SHADOWMAP MOTION boolean 
{ options->shadow_map_motion = $3; } 
| SHADOWMAP REBUILD boolean 
{ options->recompute_shadow_maps = (($3)?’y’:’n’); 
options->shadowmap_flags &= ~miSHADOWMAP_MERGE; } 
| SHADOWMAP REBUILD MERGE 
{ options->recompute_shadow_maps = ’m’; 
options->shadowmap_flags |= miSHADOWMAP_MERGE; } 
| SHADOWMAP boolean 
{ options->use_shadow_maps &= 0x80; 
options->shadowmap_flags &= ~miSHADOWMAP_DETAIL; 
if ($2) options->use_shadow_maps |= 1; 
else options->use_shadow_maps = 0; } 
| SHADOWMAP OPENGL 
{ options->use_shadow_maps &= 0x80; 
options->use_shadow_maps |= ’o’; } 
| SHADOWMAP TRACE 
{ options->shadowmap_flags |= miSHADOWMAP_TRACE; } 
| SHADOWMAP TRACE boolean 
{ if ($3) 
options->shadowmap_flags |= miSHADOWMAP_TRACE; 
else 
options->shadowmap_flags &=“miSHADOWMAP_TRACE; } 
| SHADOWMAP WINDOW 
{ options->shadowmap_flags |= miSHADOWMAP_CROP; } 
| SHADOWMAP WINDOW boolean 
{ if ($3) 
options->shadowmap_flags |= miSHADOWMAP_CROP; 
else 
options->shadowmap_flags &= ~miSHADOWMAP_CROP; } 
| SHADOWMAP ONLY 
{ options->use_shadow_maps |= 0x80; 
options->shadowmap_flags |= miSHADOWMAP_ONLY; } 
| SHADOWMAP DETAIL 
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{ options->use_shadow_maps &= 0x80; 


SHADOWMAP BIAS floating 
{ options->shadowmap_bias 
LIGHTMAP boolean 
{ options->lightmap 


options->use_shadow_maps |= ’d’; 
options->shadowmap_flags |= miSHADOWMAP_DETAIL; } 


LIGHTMAP ONLY 


{ 
CAUSTIC 


{ 
CAUSTIC 


{ 
CAUSTIC 


{ 
CAUSTIC 


CAUSTIC 
3 


CAUSTIC 
{ 


CAUSTIC 
{ 


GLOBILLUM boolean 


options->lightmap 


boolean 


options->caustic 
T_INTEGER 


= $3; } 


$2 ? miLIGHTMAP_ON 


: miLIGHTMAP_OFF; } 


miLIGHTMAP_ONLY; } 


$2; 


z 


options->caustic_flag = $2; } 


ACCURACY T_INTEGER 


options->caustic_accuracy = $3; } 
ACCURACY T_INTEGER floating 
options->caustic_accuracy = $3; 


options-—>caustic_radius 


FILTER c_filter_type 


options->caustic_filter = 


= $4; } 


$3; 


options->caustic_filter_const = 
FILTER c_filter_type floating 


options->caustic_filter 


= $3; 


options->caustic_filter_const = 


SCALE color 


options->caustic_scale 


{ options->globillum 


GLOBILLUM T_INTEGER 


= $3; } 


$2; } 


{ options->globillum_flag = $2; } 
GLOBILLUM ACCURACY T_INTEGER 
{ options->globillum_accuracy = $3; } 
GLOBILLUM ACCURACY T_INTEGER floating 


{ options->globillum_accuracy = $3; 


GLOBILLUM SCALE color 


options->globillum_radius = $4; } 


{ options->globillum_scale = $3; 


FINALGATHER boolean 

{ options->finalgather 
FINALGATHER FASTLOOKUP 

{ options->finalgather 
FINALGATHER ONLY 

{ options->finalgather 


FINALGATHER ACCURACY T_INTEGER 
{ options->finalgather_view 
options->finalgather_rays 
FINALGATHER ACCURACY T_INTEGER floating 
{ options->finalgather_view 
options->finalgather_rays 


$2; } 
go F 
ae 


options->finalgather_maxradius 
options->finalgather_minradius 


= miFALSE; 


miFALSE; 


$3; } 


$3 ; 
$4 ; 
0.0% 7 


FINALGATHER ACCURACY T_INTEGER floating floating 
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{ options->finalgather_view miFALSE; 
options->finalgather_rays = $3; 
options->finalgather_maxradius = $4; 
options->finalgather_minradius = $5; } 

FINALGATHER ACCURACY VIEW T_INTEGER 

{ options->finalgather_view = miTRUE; 

options->finalgather_rays $4; } 
FINALGATHER ACCURACY VIEW T_INTEGER floating 

{ options->finalgather_view = miTRUE; 
options->finalgather_rays = $4; 
options-—>finalgather_maxradius = $5; 
options->finalgather_minradius = 0.0; } 

FINALGATHER ACCURACY VIEW T_INTEGER floating floating 


{ options->finalgather_view = miTRUE; 
options->finalgather_rays = $4; 
options->finalgather_maxradius = $5; 
options->finalgather_minradius = $6; } 


FINALGATHER FILE_ map_list 
{ mi_api_taglist_reset (koptions->finalgather_file, 
$3); } 
FINALGATHER FILTER T_INTEGER 


{ options->finalgather_filter = $3; } 
| FINALGATHER REBUILD boolean 
{ options->finalgather_rebuild = $3; } 


FINALGATHER REBUILD FREEZE 

{ options->finalgather_rebuild = 2; } 
FINALGATHER FALLOFF floating floating 

{ options->fg_falloff_start = $3; 


options->fg_falloff_stop = $4; } 
| FINALGATHER FALLOFF floating 
{ options->fg_falloff_start = $3; 
options->fg_falloff_stop = $3; } 


FINALGATHER SCALE color 

{ options->finalgather_scale = $3; } 
FINALGATHER PRESAMPLE DENSITY floating 

{ options->fg_presamp_density = $4; } 
PHOTONVOL ACCURACY T_INTEGER 


{ options->photonvol_accuracy = $3; } 
| PHOTONVOL ACCURACY T_INTEGER floating 
{ options->photonvol_accuracy = $3; 


options->photonvol_radius $4; } 
PHOTONMAP FILE_ 
{ mi_scene_delete(options->photonmap_file) ; 
options->photonmap_file = 0; } 
PHOTONMAP FILE_ T_STRING 
{ mi_scene_delete(options->photonmap_file) ; 
strcpy((char *)mi_scene_create( 
&options->photonmap_file, 
miSCENE_STRING, strlen($3)+1), $3); 
mi_db_unpin(options->photonmap_file) ; 
mi_mem_release($3); } 
PHOTONMAP ONLY 
{ options->photonmap_only = miTRUE; } 
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PHOTONMAP ONLY boolean 
{ options->photonmap_only = $3; } 
PHOTONMAP REBUILD boolean 
{ options->photonmap_rebuild = $3; } 
APPROXIMATE opt_displace 
FRAME BUFFER T_INTEGER opt_symbol 
{ mi_api_framebuffer(options, $3, $4); } 
LUMINANCE WEIGHT NTSC 
{ options->luminance_weight.r = 0.299; 
options->luminance_weight.g = 0.587; 
options->luminance_weight.b = 0.114; 
options->luminance_weight.a = 0.0; } 
LUMINANCE WEIGHT floating floating floating 
{ options->luminance_weight.r = $3; 
options->luminance_weight.g = $4; 
options->luminance_weight.b = $5; 
options->luminance_weight.a = 0; } 
MAX_ DISPLACE floating 
{ options->maxdisplace = $3; } 


map_list met 
{ taglist = mi_api_dlist_create(miDLIST_TAG); } 
map_list_items ’]’ 
{ $$ = taglist; } 
T_STRING 
{ taglist = mi_api_dlist_create(miDLIST_TAG) ; 
strcpy((char *)mi_scene_create( 
&tag, miSCENE_STRING, strlen($1)+1), $1); 
mi_scene_edit_end (tag) ; 
mi_mem_release($1) ; 
mi_api_dlist_add(taglist, (void *) (miIntptr)tag) ; 
$$ = taglist; } 


{ $$ = NULL; } 


map_list_items : T_STRING 
{ strcpy((char *)mi_scene_create( 
&tag, miSCENE_STRING, strlen($1)+1), $1); 
mi_scene_edit_end (tag) ; 
mi_mem_release($1) ; 
mi_api_dlist_add(taglist, (void *)(milIntptr)tag); } 
map_list_next 


map_list_next 


| ee 


| ’?,? map_list_items 


filter_type : BOX 
ee Pah so 
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c_filter_type 


opt_displace 


camera 


camera_list 


camera_item 


TRIANGLE 

{ $$ = °’t’; } 
GAUSS 

{ $$ = ’g’; } 
MITCHELL 

{ $$ = ’m’; } 
LANCZOS 

{ Sh = 71*; } 
CLIP MITCHELL 

{ $$ = °M’; } 
CLIP LANCZOS 

{ $$ = °c’; } 

: BOX 

{ $$ = ’b’; } 
CONE 

{ $$ = *c?s } 
GAUSS 

{ $$ = °g’; } 


{ miAPPROX_DEFAULT (approx); } 
S_approx_tech ALL 
{ memcpy (koptions->approx, kapprox, sizeof (miApprox)) ;} 
{ miAPPROX_DEFAULT (approx); } 
DISPLACE s_approx_tech ALL 
{ memcpy (koptions->approx_displace, &approx, 
sizeof (miApprox)); } 


: CAMERA symbol 


{ camera = mi_api_camera_begin ($2) ; 
have_l = have_o = have_v = have_e = have_p = 0; } 
camera_list END CAMERA 
{ mi_api_camera_end(); } 


camera_list camera_item 


>: Camview_item 


frame_number 
FIELD T_INTEGER 
{ camera->frame_field = $2; } 
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Camview_item : QUTPUT 
{ mi_api_function_delete(&camera->output); } 
| OUTPUT colorspace_set T_STRING T_STRING 
{ if (!have_o++) 
mi_api_function_delete(&camera->output) ; 
mi_api_output_colorprofile($2) ; 
camera->output = mi_api_function_append( 
camera->output, 
mi_api_output_file_def(0, 0, $3, $4)); } 
| OUTPUT colorspace_set T_STRING out_parms T_STRING 
{ miTag ftag; 
if (!have_o++) 
mi_api_function_delete(&camera->output) ; 
mi_api_output_colorprofile($2) ; 
camera->output = mi_api_function_append( 
camera->output, 
ftag = mi_api_output_file_def(0, 0, $3, $5)); 
mi_api_output_file_parameter(ftag, 0, &$4[0]); 
mi_api_output_file_parameter(ftag, 1, &$4[1]); 
mi_api_output_file_parameter(ftag, 4, &$4[4]); 
mi_api_output_file_parameter(ftag, 6, &$4[6]); } 
| OUTPUT colorspace_set T_STRING T_STRING T_STRING 
{ if ('have_ot+) 
mi_api_function_delete(&camera->output) ; 
mi_api_output_colorprofile($2) ; 
mi_api_output_type_identify(&tbm, &ibm, $3); 
camera->output = mi_api_function_append( 
camera->output, 
mi_api_output_file_def(tbm, ibm, $4, $5));} 
| OUTPUT colorspace_set T_STRING T_STRING out_parms T_STRING 
{ miTag ftag; 
if (!have_o++) 
mi_api_function_delete(&camera->output) ; 
mi_api_output_colorprofile ($2) ; 
mi_api_output_type_identify(&tbm, &ibm, $3); 
camera->output = mi_api_function_append( 
camera->output, 
ftag = mi_api_output_file_def(tbm, ibm,$4,$6)) ; 
mi_api_output_file_parameter(ftag, 0, &$5[0]); 
mi_api_output_file_parameter(ftag, 1, &$5[1]); 
mi_api_output_file_parameter(ftag, 4, &$5[4]); 
mi_api_output_file_parameter(ftag, 6, &$5[6]); } 
| OUTPUT colorspace_set function 
{ if (!have_o++) 
mi_api_function_delete(&camera->output) ; 
mi_api_output_colorprofile($2) ; 
camera->output = mi_api_function_append( 
camera->output, 
mi_api_output_function_def(0, 0, $3)); } 
| OUTPUT colorspace_set T_STRING function 
{ if ('thave_o++) 
mi_api_function_delete(&camera->output) ; 
mi_api_output_colorprofile($2) ; 
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mi_api_output_type_identify(&tbm, &ibm, $3); 
camera->output = mi_api_function_append( 
camera->output, 
mi_api_output_function_def(tbm, ibm, $4)); } 
| PASS NULL_ 
{ mi_api_function_delete(&camera->pass); } 
| PASS pass_samples opt_string WRITE T_STRING 
{ if (!have_p++) 
mi_api_function_delete(&camera->pass) ; 
mi_api_output_type_identify(&tbm, &ibm, $3); 
camera->pass = mi_api_function_append(camera->pass, 
mi_api_pass_save_def(tbm, ibm, $2, $5)); } 
| PASS PREP pass_samples opt_string 
READ T_STRING WRITE T_STRING function_list 
{ if (!have_pt++) 
mi_api_function_delete(&camera->pass) ; 
mi_api_output_type_identify(&tbm, &ibm, $4); 
camera->pass = mi_api_function_append(camera->pass, 
mi_api_pass_prep_def(tbm, ibm, $3, $6,$8,$9));} 
| PASS MERGE pass_samples opt_string 
READ string_list opt_function_list 
{ if ('!have_p++) 
mi_api_function_delete(&camera->pass) ; 
mi_api_output_type_identify(&tbm, &ibm, $4); 
camera->pass = mi_api_function_append(camera->pass, 
mi_api_pass_merge_def(tbm, ibm, $3, $6,0,$7));} 
| PASS MERGE pass_samples opt_string 
READ string_list WRITE T_STRING opt_function_list 
{ if (!have_pt++) 
mi_api_function_delete(&camera->pass) ; 
mi_api_output_type_identify(&tbm, &ibm, $4); 
camera->pass = mi_api_function_append(camera->pass, 
mi_api_pass_merge_def(tbm,ibm, $3, $6,$8,$9));} 
| PASS DELETE_ T_STRING 
{ if (!have_p++) 
mi_api_function_delete(&camera->pass) ; 
camera->pass = mi_api_function_append(camera->pass, 
mi_api_pass_delete_def($3)); } 
PASS MASK boolean 
{ camera->pass_mask = $3; } 
| VOLUME 
{ mi_api_function_delete(&camera->volume); } 
| VOLUME function_list 
{ if (!have_v++) 
mi_api_function_delete(&camera->volume) ; 


camera->volume = mi_api_function_append ( 
camera->volume, $2); } 


ENVIRONMENT 
{ mi_api_function_delete(&camera->environment); } 
ENVIRONMENT function_list 
{ if (!have_e++) 
mi_api_function_delete(&camera->environment) ; 
camera->environment = mi_api_function_append( 


762 


out_parms 
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camera->environment, $2); } 


LENS 


{ mi_api_function_delete(&camera->lens) ; } 


LENS function_list 
{ if ('have_1++) 


mi_api_function_delete(&camera->lens) ; 


camera->lens = mi_api_function_append( 
camera->lens, $2); } 


FOCAL floating 
{ camera->focal = $2; 
Ccamera->orthographic = 
FOCAL INFINITY_ 
{ camera->focal = 1; 
Ccamera->orthographic = 
APERTURE floating 
{ camera->aperture = $2; 
ASPECT floating 
{ camera->aspect = $2; } 
RESOLUTION T_INTEGER T_INTEGER 
{ camera->x_resolution = 
camera->y_resolution = 
OFFSET floating floating 
{ camera->x_offset = $2; 
camera->y_offset = $3; 


WINDOW T_INTEGER T_INTEGER T_INTEGER T_INTEGER 


{ camera->window.xl = $2; 
camera->window.yl = $3; 
camera->window.xh = $4; 
camera->window.yh = $5; 

CLIP floating floating 

{ camera->clip.min = $2; 

camera->clip.max = $3; 
DOF floating floating 

{ camera->focus 

camera->radius = $3; } 


I 
A 
NO 


{ curr_datatag = &camera->userdata; } 


data 


: QUALITY T_INTEGER 


{ $$[0] = (float)$2; } 


EVEN 

{ $$[1] = 1.0; } 
ODD 

{ $$[1] = 2.0; } 
DOD 


{ $$[4] = 1.0; } 
DPI floating 
{ $$[6] = $2; } 
COMPRESS T_STRING 
{ if (!strcmp($2, "none") 
$$(0] = 1.0; 


miFALSE; } 


miTRUE; } 


} 


$2; 
$3; } 


: 


) 


else if (!strcmp($2, "piz")) 
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frame_number 


colorspace_set 


pass_samples 


string_list 


strings 


* instance 


$$L0] = 2.0; 

else if (!strcmp($2, "zip")) 
$$[0] = 3.0; 

else if (!strcmp($2, "rle")) 
$$[0] = 4.0; 

else if (!strcmp($2, "pxr24")) 
$$L0] = 5.0; 

else { 


mi_api_error("%s is not a valid compression 
"type, using rle compression", 


$2) ; 
$$[0] = 4.0; 
Ne 
} 
: FRAME T_INTEGER 
{ camera->frame = $2; 
camera->frame_time = QO; 


II 
oe) 
WY 


camera->frame_field 
FRAME T_INTEGER floating 
{ camera->frame = $2; 
camera->frame_time 
camera->frame_field 


oe 

Of 
we WwW 
Ww 


{ $$ = 0; } 
COLORPROFILE symbol 

{ $$ = $2; } 

{ $$ = ~0O; } 
SAMPLES T_INTEGER 

{ $$ = $2; } 

{ $$ = stringlist 


mi_api_dlist_create(miDLIST_POINTER) ; } 
tL? pirines 71+ 


: T_STRING 
{ mi_api_dlist_add(stringlist, $1); } 
Leo eee Leas 
{ mi_api_dlist_add(stringlist, $1); } 
strings 
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instance 


inst_item 


inst_func 


inst_flags 


inst_flag 


INSTANCE symbol 


{ curr_inst = mi_api_instance_begin ($2) ; 


if (!curr_inst) { 


memset (kdummy_inst, 0, sizeof (dummy_inst)) ; 


curr_inst = &dummy_inst; 


} 

override = miFALSE; } 
inst_item inst_func 
inst_flags 
inst_params 


{ mi_api_instance_end($4, $5, $7); } 


END INSTANCE 


{ $$ = 0; } 
symbol 
{ $$ = $1; } 
{ $$ = miNULLTAG; } 


GEOMETRY function_list 
{ $$ = $2; } 


inst_flag inst_flags 


: VISIBLE boolean 


{ curr_inst->visible 
SHADOW boolean 

{ curr_inst->shadow 
SHADOW T_INTEGER 

{ curr_inst->shadow 
SHADOWMAP boolean 

{ curr_inst->shadowmap 
TRACE boolean 

{ curr_inst->reflection 

curr_inst->refraction 


curr_inst->finalgather 


REFLECTION T_INTEGER 

{ curr_inst-—>reflection 
REFRACTION T_INTEGER 

{ curr_inst->refraction 
TRANSPARENCY T_INTEGER 


{ curr_inst->transparency 


FACE FRONT 
{ curr_inst->face 
FACE BACK 


ea a ae | 

$2 ? 0x03 : 0x06; } 
($2 & Ox0f); } 

$2 72+ 13 } 

$2 7 0x03 : Ox0c; 
$2 ? 0x23 : Ox10; } 
($2 & OxOf); } 

($2 & OxOf); } 

= ($2 & Ox0f); } 


ar 
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{ curr_inst->face = 
FACE BOTH 
{ curr_inst->face = 
SELECT boolean 
{ curr_inst->select = 
CAUSTIC 
{ curr_inst->caustic & 
curr_inst->caustic |= 
CAUSTIC boolean 
{ curr_inst->caustic &= 
curr_inst->caustic |= 
CAUSTIC T_INTEGER 
{ curr_inst->caustic & 
curr_inst->caustic | = 
GLOBILLUM 
{ curr_inst->globillum &= 
curr_inst->globillum |= 
GLOBILLUM boolean 
{ curr_inst->globillum &= 
curr_inst->globillum |= 
GLOBILLUM T_INTEGER 
{ curr_inst->globillum &= 
curr_inst->globillum |= 
FINALGATHER 


So09°S 2.45 > 


0x30; 

0x03; } 

OxOt ; 

$2 7 0x20 : Oxi0: } 
0x30; 


($2 & OxOf); } 


0230 

0x03; } 

Ox0t ; 

S>. 7-020: : 0x10; } 
0x30; 


($2 & OxOf); } 


{ curr_inst->finalgather &= 0x30; 


curr_inst->finalgather 
FINALGATHER boolean 
{ curr_inst->finalgather 
curr_inst->finalgather 
FINALGATHER T_INTEGER 
{ curr_inst->finalgather 
curr_inst->finalgather 
HIDE boolean 
{ curr_inst->off = $2; } 
TRANSFORM 
{ curr_inst->tf.function 


TRANSFORM function 


l= 0x03; } 

&= OxOF; 

l= $2 7? 0x20 : 0x10; } 
&= 0x30; 


l= ($2 & Ox0f); } 


= miNULLTAG; 
mi_matrix_ident (curr_inst->tf.global_to_local); } 


{ curr_inst->tf.function = $2; 


mi_matrix_ident (curr_inst->tf.global_to_local); } 


transform 
{ curr_inst->tf.function 
mi_matrix_copy ( 


= miNULLTAG; 


curr_inst->tf.global_to_local, $1); 


if (!mi_matrix_invert (curr_inst->tf.local_to_global, 
curr_inst->tf.global_to_local)){ 
mi_api_warning("singular matrix, using 
"identity"); 
mi_matrix_ident (curr_inst->tf.global_to_local) ; 
mi_matrix_ident (curr_inst->tf.local_to_global) ; 


tt 
MOTION OFF 


{ mi_matrix_null(curr_inst->motion_transform) ; 
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curr_inst->gen_motion = miGM_OFF; } 
MOTION TRANSFORM 
{ mi_matrix_null(curr_inst->motion_transform) ; 
curr_inst->gen_motion = miGM_INHERIT; } 
| MOTION transform 
{ mi_matrix_copy(curr_inst->motion_transform, $2); 
curr_inst->gen_motion = miGM_TRANSFORM; } 
MATERIAL 
{ curr_inst->material = miNULLTAG; 
curr_inst->mtl_array_size = 0; 
miFALSE; } 


curr_inst->mtl_override 
inst_mtl 
| TAG T_INTEGER 
{ curr_inst->label = $2; } 
| { curr_datatag = &curr_inst->userdata; } 


data 
| OVERRIDE 
{ override = miTRUE; } /* for approx and material */ 
| APPROXIMATE 
{ mi_api_instance_approx(0, miFALSE); } 
| APPROXIMATE 


{ miAPPROX_DEFAULT (approx) ; 
curr_inst->approx_override = override; 
override = miFALSE; } 

?[? inst_approx_arr ’]’ 


inst_params 
{ $$ 
Stes, 
{ $$ 


(miTag)-1; } 


miNULLTAG; } 
, *(? 
{ if (!ctx->inheritance_func) 
mi_api_error("no inheritance function in options") ; 
else 
mi_api_function_call(mi_mem_strdup ( 
ctx->inheritance_func)); } 
parameter_seq comma_rparen 
{ $$ = mi_api_function_call_end(0); } 


comma_rparen es So 
[4 
inst_mtl 
| symbol 
{ curr_inst->material = mi_api_material_lookup($1) ; 
curr_inst->mtl_override = override; 
override = miFALSE; } 
Ras 


{ taglist = mi_api_dlist_create(miDLIST_TAG); } 
ingtentl, array *]* 
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{ curr_inst->mtl_array_size = taglist-—>nb; 
curr_inst->material mi_api_taglist(taglist) ; 
curr_inst->mtl_override override; } 


inst_mtl_array : symbol 
{ mi_api_dlist_add(taglist, 
(void *) (milntptr)mi_api_material_lookup($1)) ;} 
inst_mtl_next 


inst_mtl_next 
| o3 


| ?,? inst_mtl_array 


inst_approx_arr : approx_flags APPROXIMATE s_approx_tech ALL 
{ mi_api_instance_approx(&approx, miFALSE) ; 
miAPPROX_DEFAULT (approx); } 
inst_approx_nxt 
| approx_flags APPROXIMATE DISPLACE s_approx_tech ALL 
{ mi_api_instance_approx(approx, miTRUE) ; 
miAPPROX_DEFAULT (approx); } 
inst_approx_nxt 


inst_approx_nxt 


| ts 


| °,? inst_approx_arr 


instgroup : INSTGROUP symbol 
{ curr_group = mi_api_instgroup_begin($2) ; 
mi_api_instgroup_clear(); } 
group_flags 
group_body END INSTGROUP 
{ mi_api_instgroup_end(); } 


group_flags 
| group_flag group_flags 


group_flag : MERGE floating 
{ curr_group->merge = $2; 
curr_group->merge_group = $2 >= miMERGE_MIN; } 
| TAG T_INTEGER 
{ curr_group->label = $2; } 
| { curr_datatag = &curr_group->userdata; } 
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data 
group_body : group_kids 
{ curr_group->placeholder = miFALSE; } 
| group_ph 
{ curr_group->placeholder = miTRUE; } 
group_ph : group_ph_item group_ph 


| group_ph_item 


group_ph_item : MAX_ DISPLACE floating 
{ curr_group->maxdisplace = $3; } 
| BOX vector vector 
{ curr_group->bbox_min = $2; 
curr_group->bbox_max = $3; } 


| BOX 
{ curr_group->bbox_min = nullvec; 
curr_group->bbox_max = nullvec; } 
| MOTION BOX vector vector 
{ curr_group->bbox_min_m = $3; 
curr_group->bbox_max_m = $4; } 
| MOTION BOX 
{ curr_group->bbox_min_m = nullvec; 
curr_group->bbox_max_m = nullvec; } 
| FILE_ T_STRING 
{ mi_api_instgroup_file($2); } 


group_kids 
| symbol 
{ mi_api_instgroup_additem($1); } 
group_kids 


RRO OOO OO II IR IR IR IK IK I RK 2K 2 2 2k 2k 2 2 2k 2k 2 a a 2k 2k 2k ok 
2K 2K 2K 2K 2K 2K 2K 2K 6 2K 2K 2K 2K 2 2 2 2 2k 2k 2K 2k 2K 2K 2K either 2K 2K 2K 2K 2K 2K 2 2K OK 2K 2K 2 2K 2K 2K 2K 2K 2K 2K 2K 2 2K 2K 2K 2 2K OK 2K 2K 2K OK 2K 2K 2K 2K 2K OK 2K 
FCO I I IR IR I aK ak ak 2k 2k 2k 2 3 3k 2k 2k 2k 2k 2 3 3 3k 2k ak ak 2k 2 26 3k ok ak ak ak ak 2k 2 2 ak / 


/*----------------------------------------------------------- --- = -- = ------ = 
* function declaration 
#*#---—---------------- --- ---- -- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - * / 

function_decl : shret_type_nosh T_STRING parm_decl_list 


{ mi_api_funcdecl_begin($1, $2, $3); 
mi_api_funcdecl_end(); } 
| SHADER shret_type T_STRING parm_decl_list 
{ if (!(curr_decl = mi_api_funcdecl_begin($2,$3,$4))){ 
memset (&dummy_decl, 0, sizeof (dummy_decl)) ; 
curr_decl = &dummy_decl; 


oy 
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declare_req_seq END DECLARE 
{ mi_api_funcdecl_end(); } 


shret_type : Shret_type_nosh 
{ $$ = $1; } 
SHADER 
{ $$ = mi_api_parameter_decl(miTYPE_SHADER, 0, 0); } 


shret_type_nosh : 
{ $$ = mi_api_parameter_decl(miTYPE_COLOR, 0, 0); } 
| simple_type 
{ $$ = mi_api_parameter_decl($1, 0, 0); } 
| STRUCT ’{’ shret_decl_seq ’}?’ 
{ miParameter *parm = 
mi_api_parameter_decl(miTYPE_STRUCT, 0, 0); 
mi_api_parameter_child(parm, $3); 
$$ = parm; } 


shret_decl_seq : shret_decl_seg ’,’ shret_decl 
{ $$ = mi_api_parameter_append($1, $3); } 


| shret_decl 
{ $$ = $1; } 
shret_decl : Simple_type symbol 


{ $$ = mi_api_parameter_decl($1, $2, 0); } 
| SHADER symbol 

{ $$ = mi_api_parameter_decl(miTYPE_SHADER, $2, 0); } 
| DATA symbol 

{ $$ = mi_api_parameter_decl(miTYPE_DATA, $2, 0); } 


parm_decl_list : ’(’ parm_decl_seg ’)’ 
{ $$ = $2; } 
| *{? para decl seq 7,7) 7%)? 
{ $$ = $2; } 
| ey 
{ $$ = 0; } 
parm_decl_seq : parm_decl_seq ’,’ parm_decl 
{ $$ = mi_api_parameter_append($1, $3); } 
| parm_decl 
{ $$ = $1; } 
parm_decl : decl_simple decl_default 
{ $$ = $1; } 


| SHADER symbol 
{ $$ = mi_api_parameter_decl(miTYPE_SHADER, $2, 0); } 
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| DATA symbol 
{ $$ = mi_api_parameter_decl(miTYPE_DATA, $2, 0); } 
| STRUCT symbol ’{’ parm_decl_seq ’}’ 
{ miParameter *parm = 
mi_api_parameter_decl(miTYPE_STRUCT, $2, 0); 
mi_api_parameter_child(parm, $4); 
$$ = parm; } 
| ARRAY parm_decl 
{ miParameter *parm = 
mi_api_parameter_decl(miTYPE_ARRAY, 0, 0); 
mi_api_parameter_child(parm, $2); 
$$ = parm; } 


decl_simple : Simple_type symbol 
{ $$ = mi_api_parameter_decl($1, $2, 0); } 


simple_type : BOOLEAN 

{ $$ = miTYPE_BOOLEAN; } 
| INTEGER 

{ $$ = miTYPE_INTEGER; } 
| SCALAR 

{ $$ = miTYPE_SCALAR; } 
| STRING 

{ $$ = miTYPE_STRING; } 
| COLOR 

{ $$ = miTYPE_COLOR; } 
| VECTOR 

{ $$ = miTYPE_VECTOR; } 
| TRANSFORM 


{ $$ = miTYPE_TRANSFORM; } 
| SCALAR TEXTURE 

{ $$ = miTYPE_SCALAR_TEX; } 
| VECTOR TEXTURE 

{ $$ = miTYPE_VECTOR_TEX; } 
| COLOR TEXTURE 

{ $$ = miTYPE_COLOR_TEX; } 


| LIGHTPROFILE 
{ $$ = miTYPE_LIGHTPROFILE; } 
| SPECTRUM 
{ $$ = miTYPE_SPECTRUM; } 
| LIGHT 
{ $$ = miTYPE_LIGHT; } 
| MATERIAL 
{ $$ = miTYPE_MATERIAL; } 
| GEOMETRY 


{ $$ = miTYPE_GEOMETRY; } 


decl_default 
| DEFAULT decl_def_values 
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decl_def_values : 


decl_def_value 


declare_req_seq 


declare_req 


decl_def_value decl_def_ 


: boolean 


{ int value = $1; 


mi_api_parameter_default(miTYPE_BOOLEAN, &value); } 


T_INTEGER 
{ int value = $1; 


mi_api_parameter_default (miTYPE_INTEGER, &value); } 


T_FLOAT 


values 


{ float value = $1; 


mi_api_parameter_default (miTYPE_SCALAR, 


declare_req declare_req_seq 


gui 
SCANLINE OFF 


{ curr_decl->phen. 


SCANLINE ON 


{ curr_decl->phen. 


TRACE OFF 


{ curr_decl->phen. 


TRACE ON 


{ curr_decl->phen. 


SHADOW OFF 


{ curr_decl->phen. 


SHADOW ON 


{ curr_decl->phen. 


SHADOW SORT 


{ curr_decl->phen. 


SHADOW SEGMENTS 


{ curr_decl->phen. 


FACE FRONT 


{ curr_decl->phen. 


FACE BACK 


{ curr_decl->phen. 


FACE BOTH 


{ curr_decl->phen. 


TEXTURE T_INTEGER 


{ curr_decl->phen. 


BUMP T_INTEGER 


{ curr_decl->phen. 


DERIVATIVE 


{ curr_decl->phen. 
.deriv2 = 0; } 


curr_decl->phen 
DERIVATIVE T_INTEGER 
{af ($2>=<-1) 


curr_decl- 


scanline = 1; } 
scanline = 2; } 
trace = 1; } 


trace = 2: } 


shadow = 1; } 
shadow = 2; } 


shadow = °1’; } 


shadow = ’s’; } 
faces = °f*: } 
face = *b’; } 
face = ’a’: } 


minbumps = $2; } 


derivi 


>phen.derivi = miTRUE; 
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else if ($2 == 2) 
curr_decl->phen.deriv2 = miTRUE; 
else 
mi_api_error("derivative not 1 or 2"); } 
| DERIVATIVE T_INTEGER T_INTEGER 
{ if ($2 == || $3 == 1) 
curr_decl->phen.derivi = miTRUE; 
else if ($2 == 2 || $3 == 2) 
curr_decl->phen.deriv2 = miTRUE; 
if ($2 != 1 && $2 !=2 || $3 != 1 && $3 != 2) 
mi_api_error("derivative not 1 or 2"); } 


OBJECT SPACE 


{ curr_decl->phen.render_space = ’o’; } 
| CAMERA SPACE 

{ curr_decl->phen.render_space = ’c’; } 
| MIXED SPACE 

{ curr_decl->phen.render_space = ’m’; } 


WORLD SPACE 
{ mi_api_warning("world space statement ignored"); } 
PARALLEL_ 
{ curr_decl->phen.parallel = miTRUE; } 
| VOLUME LEVEL T_INTEGER 
{ curr_decl->phen.volume_level = $3; } 
VERSION T_INTEGER 
{ curr_decl->version = $2; } 
| APPLY apply_list 
{ curr_decl->apply = $2; } 


apply_list : apply { $$ = $1; } 
| apply ’,’ apply_list { $$ = $1 | $3; } 

apply : LENS { $$ = miAPPLY_LENS; } 
| MATERIAL { $$ = miAPPLY_MATERIAL; } 
| LIGHT { $$ = miAPPLY_LIGHT; } 
| SHADOW { $$ = miAPPLY_SHADOW; } 
| ENVIRONMENT { $$ = miAPPLY_ENVIRONMENT; } 
| VOLUME { $$ = miAPPLY_VOLUME; } 
| TEXTURE { $$ = miAPPLY_TEXTURE; } 
| PHOTON { $$ = miAPPLY_PHOTON; } 
| GEOMETRY { $$ = miAPPLY_GEOMETRY ; } 
| DISPLACE { $$ = miAPPLY_DISPLACE; } 
| EMITTER { $$ = miAPPLY_PHOTON_EMITTER; } 
| OUTPUT { $$ = miAPPLY_OUTPUT; } 
| LIGHTMAP { $$ = miAPPLY_LIGHTMAP; } 
| PHOTONVOL { $$ = miAPPLY_PHOTONVOL; } 
| STATE { $$ = miAPPLY_STATE; } 


* function instance 
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Spt _tunction. list: 


function_list 


Func. List 


function 


opt_incremental : 


parameter_list 


parameter_seq 


parameter 


value_list 


—------------------------------------ -- - - - - - - - - - - - - - - * / 
{ $$ = 0; } 

function_list 
{ $$ = $1; } 


{ funclist = miNULLTAG; } 
Tunc. list 
{ $$ = funclist; } 


: function 


{ funclist = $1; } 
func_list function 
{ funclist = mi_api_function_append(funclist, $2); } 


: T_STRING 


{ mi_api_function_call($1); } 
parameter_list 
{ $$ = mi_api_function_call_end(functag); functag = 0;} 
?=? symbol 
{ $$ = mi_api_function_assign($2); } 
?=? opt_incremental SHADER symbol function 
{ mi_api_shader_add($4, $5); $$ = $5; 
mi_api_incremental(is_incremental) ; 
mi_api_private(session_depth); } 


{ mi_api_incremental(miFALSE); } 
INCREMENTAL 
{ mi_api_incremental(miTRUE) ; } 


ac? »)? 
?(? parameter_seq ’)’ 
?(? parameter_seg ’,’ ’)’ 


parameter 
parameter_seq ’,’ parameter 


>: symbol 


{ mi_api_parameter_name($1); } 
value_list 


: value 
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value 


array_value_seq : 


array_value_cont: 


userdata 
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value_list value 


NULL_ 
boolean 
{ int value = $1; 
mi_api_parameter_value(miTYPE_BOOLEAN, &value,0,0); } 
T_INTEGER 
{ int value = $1; 
mi_api_parameter_value(miTYPE_INTEGER, &value,0,0); } 
T_FLOAT 
{ float value = $1; 
mi_api_parameter_value(miTYPE_SCALAR, &value,0,0); } 
symbol 
{ mi_api_parameter_value(miTYPE_STRING, $1, 0, 0); } 
>=? symbol 
{ mi_api_parameter_shader ($2); } 
?=? INTERFACE_ symbol 
{ mi_api_parameter_interface($3); } 
>? 
{ mi_api_parameter_push(miFALSE); } 
parameter_seq ’}’ 
{ mi_api_parameter_pop(); } 
mt? 
{ mi_api_parameter_push(miTRUE); } 
array_value_seg ’]’ 
{ mi_api_parameter_pop(); } 
) [? a 
{ mi_api_parameter_push(miTRUE) ; 
mi_api_parameter_pop(); } 


{ mi_api_new_array_element () ; } 
value_list 
array_value_cont 


{ mi_api_new_array_element(); } 
value_list array_value_cont 


: DATA symbol data_label T_INTEGER 


{ curr_data = mi_api_data_begin($2, 0, 
(void *) (milIntptr) $4) ; 
curr_data->label = label; } 
*[*? data_bytes_list °*]° 
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data_label 


data_bytes_list 


data_decl 


data_decl_req 


data 


{ mi_api_data_end(); } 
DATA symbol data_label symbol 
{ curr_data = mi_api_data_begin($2, 1, 


(void *) (milntptr) $4) ; 


curr_data->label = label; 
mi_api_data_end(); } 
DATA symbol data_label symbol ’(’ 
{ mi_api_function_call($4); } 
parameter_seq comma_rparen 
{ tag = mi_api_function_call_end(0) ; 
curr_data = mi_api_data_begin($2, 2, 


(void *) (miIntptr) tag) ; 


curr_data->label = label; 
mi_api_data_end(); } 


{ label = 0; } 
TAG T_INTEGER 
{ label 


$2; } 


data_bytes_list T_BYTE_STRING 
{ mi_api_data_byte_copy($2.len, $2.bytes); } 


: DATA T_STRING parm_decl_list 


{ if (curr_decl = mi_api_funcdecl_begin(0, $2, $3)) 
curr_decl->type = miFUNCTION_DATA; } 
data_decl_req END DECLARE 
{ if (curr_decl) mi_api_funcdecl_end(); } 


gui 
VERSION T_INTEGER 

{ if (curr_decl) curr_decl->version = $2; } 
APPLY apply_list 

{ if (curr_decl) curr_decl->apply = $2; } 


: DATA symbol 


{ *curr_datatag = mi_api_data_append(*curr_datatag, 
mi_api_data_lookup($2)); } 

DATA NULL_ 
{ *curr_datatag 


II 
oO 
aye 
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phenomenon_decl 


phen_body_list 


phen_body 
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: PHENOMENON shret_type T_STRING parm_decl_list 


{ curr_decl = mi_api_phen_begin($2, $3, $4); 
if fteurridect) { 
memset (&dummy_decl, 0, sizeof (dummy_decl)) ; 
curr_decl = &dummy_decl; 
aes 
phen_body_list 
END DECLARE 
{ mi_api_phen_end(); } 


phen_body phen_body_list 


: SHADER symbol function_list 


{ mi_api_shader_add($2, $3); } 
material 
light 
instance 
declare_req 
ROOT phen_root 
{ if (curr_decl->phen.root) 
mi_api_error("multiple roots not allowed") ; 
else 
curr_decl->phen.root = $2; } 
OUTPUT T_STRING T_STRING 
{ curr_decl->phen.output = mi_api_function_append( 
curr_decl->phen.output, 
mi_api_output_file_def(0, 0, $2, $3)); } 
OUTPUT T_STRING T_STRING T_STRING 
{ mi_api_output_type_identify(&tbm, &ibm, $2); 
curr_decl->phen.output = mi_api_function_append ( 
curr_decl->phen.output, 
mi_api_output_file_def(tbm, ibm, $3, $4));} 
OUTPUT function 
{ curr_decl->phen.output = mi_api_function_append( 
curr_decl->phen.output, 
mi_api_output_function_def(0, 0, $2)); } 
OUTPUT T_STRING function 
{ mi_api_output_type_identify(&tbm, &ibm, $2); 
curr_decl->phen.output = mi_api_function_append ( 
curr_decl->phen.output, 
mi_api_output_function_def(tbm, ibm, $3)); } 
LENS function_list 
{ curr_decl->phen.lens = mi_api_function_append( 
curr_decl->phen.lens, $2); } 
VOLUME function_list 
{ curr_decl->phen.volume = mi_api_function_append( 
curr_decl->phen.volume, $2); } 
ENVIRONMENT function_list 
{ curr_decl->phen.environment = mi_api_function_append( 
curr_decl->phen.environment, $2); } 
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GEOMETRY function_list 
{ curr_decl->phen.geometry = mi_api_function_append( 
curr_decl->phen.geometry, $2) ;} 

| CONTOUR STORE function 

{ curr_decl->phen.contour_store = $3; } 
| CONTOUR CONTRAST function 

{ curr_decl->phen.contour_contrast = $3; } 
| OUTPUT PRIORITY T_INTEGER 

{ curr_decl->phen.output_seqnr = $3; } 
| LENS PRIORITY T_INTEGER 

{ curr_decl->phen.lens_segnr = $3; } 
| VOLUME PRIORITY T_INTEGER 
{ curr_decl->phen.volume_segnr = $3; } 


phen_root : MATERIAL symbol 
{ if (*curr_decl->declaration != ’m’) { 
mi_api_error("not a material phenomenon") ; 
$$ = 0; 
} else 


$$ = mi_api_material_lookup($2); } 
| LIGHT symbol 


{ if (*curr_decl->declaration != ’1’) { 
mi_api_error("not a light phenomenon") ; 
$$ = 0; 
} else 


$$ = mi_api_light_lookup($2); } 
| function_list 
{ $$ = 0; 
if (*curr_decl->declaration == ’m’) 
mi_api_error("must use ‘ ‘root material’’"); 
else if (*curr_decl->declaration == ’1’) 


mi_api_error("must use ‘‘root light’’"); 


else 
$$ = mi_api_function_append( 
curr_decl->phen.root, $1); } 
/*----------------------------------- ---- - - 
* texture 
*#------------------------------------ ---- - - - - - - - = * / 
texture ; { pyramid_filter = 0.; 


curr_cprof = 0; } 
tex_flags tex_type TEXTURE symbol colorspace_set 
{ functag = mi_api_texture_begin($5, $3, $2); 
mi_api_texture_set_colorprofile ($6) ; 
mi_api_texture_set_filter(pyramid_filter); } 
tex_data 
{ if (pyramid_filter > 0. && functag && 
(mi_db_type(functag) != miSCENE_IMAGE)) { 
mi_api_nwarning(42, "cannot filter shaders") ; 
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t 
mi_api_texture_end() ; 
functag = 0; } 


tex_flags 
{ $$ = 0; } 
| tex_flag tex_flags 
{ $$ = $1 | $2; } 


tex_flag : LOCAL 
{ $$ = 1; } 
| FILTER 
{ pyramid_filter 
| FILTER floating 
{ pyramid_filter = $2; 
$$ = (pyramid_filter > 0.) ?7 2: 0; } 
WRITABLE 
{ $$ = 4; } 


1.; $$ = 2; } 


tex_type : COLOR 
{ $$ 
| SCALAR 


{ $$ 
| VECTOR 
{ $$ 


ll ll 
— ee 
ae LY 


I 
NO 
Aunpil 


tex_data : ?({? T_INTEGER T_INTEGER ’]’ 
{ mi_api_texture_array_def_begin($2, $3, 1); } 
tex_bytes_list 
{ functag = mi_api_texture_array_def_end(); } 
| ?{’ T_INTEGER T_INTEGER T_INTEGER ’]’ 
{ mi_api_texture_array_def_begin($2, $3, $4); } 
tex_bytes_list 
{ functag = mi_api_texture_array_def_end(); } 
| tex_func_list 
{ functag = mi_api_texture_function_def ($1); } 
| T_STRING 
{ functag = mi_api_texture_file_def($1); } 
| T.STRING ’[’? T_INTEGER T_INTEGER ’]’ 
{ mi_api_texture_file_size($3, $4, 1, miIMG_TYPE_ANY) ; 
functag = mi_api_texture_file_def ($1); } 
| T_STRING ’([’? T_INTEGER T_INTEGER T_INTEGER ’]’ 
{ mi_api_texture_file_size($3, $4, $5, miIMG_TYPE_ANY) ; 
functag = mi_api_texture_file_def($1); } 
| T.STRING T_STRING ’[’ T_INTEGER T_INTEGER ’]’ 
{ mi_api_texture_file_size($4, $5, 0, 
mi_api_texture_type_identify($2)) ; 
functag = mi_api_texture_file_def ($1); } 


B Scene File Grammar 


tex_func_list 


tex_bytes_list 


profile_data 


lprof_ops 


lprof_op 


: function 


{ $$ = $1; } 
function tex_func_list 
{ $$ = mi_api_function_append($1, $2); } 


tex_bytes_list T_BYTE_STRING 
{ mi_api_texture_byte_copy($2.len, $2.bytes); } 


: LIGHTPROFILE symbol 


{ lprof = mi_api_lightprofile_begin($2); } 
lprof_ops 
END LIGHTPROFILE 

{ mi_api_lightprofile_end(); } 


lprof_ops lprof_op 


: FORMAT IES 


{ lprof->format = miLP_STD_IES; } 
FORMAT EULUMDAT 
{ lprof->format = miLP_STD_EULUMDAT; } 
FLAGS T_INTEGER 
{ lprof->flags = $2; } 
FILE_ T_STRING 
{ char* fn = mi_scene_create(&lprof->filename, 
miSCENE_STRING, strlen($2)+1) ; 
strcpy(fn, $2); 
mi_mem_release($2) ; 
mi_scene_edit_end(lprof->filename); } 
HERMITE T_INTEGER 
{ lprof->base = miLP_BASIS_HERMITE; 
lprof->quality = $2; } 
RESOLUTION T_INTEGER T_INTEGER 
{ lprof->n_horz_angles = $2; 
lprof->n_vert_angles = $3; } 
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cprof 


cprof_ops 


cprof_op 


: COLORPROFILE symbol 


{ cprof = mi_api_colorprofile_begin($2); } 


cprof_ops 
END COLORPROFILE 


{ mi_api_colorprofile_end(); } 


cprof_ops cprof_op 


: COLOR SPACE T_STRING 
{ cprof->space = 
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mi_api_colorprofile_space($3); } 


TRANSFORM floating floating floating 


floating floating floating 
floating floating floating 


== miCPROF_CUSTOM) { 


{ 
if ((cprof->space & miCPROF_SPACEMASK ) 
miMatrix mat; 
cprof->space |= miCPROF_CID_NOT_ENOUGH; 
mat[lO] = $2; 
mat{i] = $3; 
mat[2] = $4; 
mat[3] = 0; 
mat[4] = $5; 
mat[5] = $6; 
mat[6] = $7; 
mat[7] = 0; 
mat[8] = $8; 
mat[9] = $9; 
mat[10] = $10; 
mat[ii] = 0; 
mat[12] = 0; 
mat[13] = 0; 
mat[14] = 0; 
mat([15] = 1; 
mi_api_colorprofile_custom(cprof, mat); 
} 
} 
| SPECTRUM 


{ cprof->space = 


cprof->white.r 
cprof->white.g 
cprof->white.b 


miCPROF_SPECTRUM ; 
mi_api_colorprofile_gamma(0.Of, 0.0f, miFALSE); } 

| WHITE floating floating 
{ /* white point chroma (x,y), intensity 1 lumen */ 
cprof->white_adapt = miTRUE; 


$2/$3; 
1.0L 
(1.0£-$2-$3) /$3; 


B Scene File Grammar 


spectrum_data 


spectrum_scalars : 


mi_colorprofile_ciexyz_to_internal (&cprof->white); } 


WHITE floating floating floating 
{ /* CIE XYZ coords of the white point */ 
cprof->white_adapt = miTRUE; 
cprof->white.r = $2; 
cprof->white.g = $3; 
cprof->white.b = $4; 


mi_colorprofile_ciexyz_to_internal (&cprof->white); } 


WHITE D T_INTEGER 
{ cprof->white_adapt = miTRUE; 
mi_api_colorprofile_white(&cprof->white, $3, 1.0f); 
WHITE D T_INTEGER floating 
{ cprof->white_adapt = miTRUE; 
mi_api_colorprofile_white(&cprof->white, $3, $4); } 
WHITE boolean 
{ cprof->white_adapt = $2; } 
GAMMA floating 
{ mi_api_colorprofile_gamma($2, 0, miFALSE); } 
GAMMA floating floating 
{ mi_api_colorprofile_gamma($2, $3, miFALSE); } 
GAMMA floating floating boolean 
{ mi_api_colorprofile_gamma($2, $3, $4); } 


: SPECTRUM symbol 


{ mi_api_spectrum_begin($2); } 
spectrum_scalars 
END SPECTRUM 

{ mi_api_spectrum_end(); } 


floating floating 

{ mi_api_spectrum_pair_add($1, $2); } 
spectrum_scalars ’,’ floating floating 

{ mi_api_spectrum_pair_add($3, $4); } 


: LIGHT symbol 


{ curr_light = mi_api_light_begin($2) ; 
light_map = 0; } 
light_ops 
END LIGHT 
{ /* 0x26 equals 100110 in binary. We want to select 


} 
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light_ops 


light_op 


* onl 
* is, 
* ad 
* / 
Switch 
case 


case 


case 


case 


case 
case 


case 


case 


t 


mi_api 


light_op light 


: function 


tae 1 


light_ 
eurr 2 


EMITTER functi 
LaF Lif 
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y the bits that identify the light type, that 
the bits that tell whether we have an origin, 
irection and a spread value. 


(light_map & 0x26) { 

O: /* if nothing is defined, default to 
* a point light 
* / 

2: /* origin only: point light */ 
curr_light->type = miLIGHT_ORIGIN; 
break; 

4: /* direction only: directional light */ 
curr_light->type = miLIGHT_DIRECTION; 
break; 

6: /* origin and direction, no spread: 

* directional light with origin 

* / 
curr_light->type = miLIGHT_DIRECTION; 
curr_light->dirlight_has_org = miTRUE; 
break; 

32: /* spread only: point light */ 

34: /* origin and spread, no direction: 

* point light 


+ / 
curr_light->type = miLIGHT_ORIGIN; 
break; 
36: /* direction and spread, no origin: 
* directional light 
* / 
curr_light->type = miLIGHT_DIRECTION; 
break; 
38: /* origin, direction and spread: 
* spot light 
*/ 
curr_light->type = miLIGHT_SPOT; 
break; 


_light_end(); } 


_ops 


light_map & 1)) 

mi_api_function_delete(&curr_light->shader) ; 

map |= 1; 

ight->shader = mi_api_function_append( 
curr_light->shader, $1); } 

on 

light_map & 8)) 

mi_api_function_delete(&curr_light->emitter) ; 
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light_map |= 8; 


curr_light->emitter = mi_api_function_append( 
curr_light->emitter, $2); } 


SHADOWMAP 
{ curr_light->use_shadow_maps 
curr_light->shadowmap_flags 
SHADOWMAP DETAIL 
{ curr_light->use_shadow_maps 
curr_light->shadowmap_flags 
SHADOWMAP DETAIL SAMPLES T_INTEGER 
{ curr_light->shmap.samples = 
SHADOWMAP MERGE 
{ curr_light->shadowmap_flags 
SHADOWMAP MERGE boolean 
{ if ($3) 


curr_light->shadowmap_flags |= miSHADOWMAP_MERGE; 


else 


curr_light->shadowmap_flags &=~miSHADOWMAP_MERGE ; 


t 
SHADOWMAP TRACE 


$ 


= miTRUE; 


O27 


miTRUE; 
= miSHADOWMAP_DETAIL; } 


4; } 


= miSHADOWMAP_MERGE; } 


{ curr_light->shadowmap_flags |= miSHADOWMAP_TRACE; } 


SHADOWMAP TRACE boolean 
{ if €$3) 


curr_light->shadowmap_flags |= miSHADOWMAP_TRACE; 


else 


curr_light->shadowmap_flags &=~miSHADOWMAP_TRACE; 


} 


SHADOWMAP WINDOW floating floating floating floating 


{ curr_light->shadowmap_flags 
curr_light->shmap_h_min = 


= miSHADOWMAP_CROP ; 


(short)miFLOOR($3 * SHRT_MAX) ; 


curr_light->shmap_v_min = 


(short)miFLOOR($4 * SHRT_MAX) ; 


curr_light->shmap_h_max = 


(short)miFLOOR($5 * SHRT_MAX) ; 


curr_light->shmap_v_max = 


(short )miFLOOR($6 * SHRT_MAX) ;} 


SHADOWMAP boolean 
{ curr_light->use_shadow_maps 
curr_light->shadowmap_flags 
SHADOWMAP CAMERA symbol 


$2; 
an a 


{ mi_api_light_shmap_camera($3); } 


SHADOWMAP BIAS floating 
{ curr_light->shadowmap_bias = 
ORIGIN vector 
{ curr_light->origin = $2; 
light_map |= 2; } 
DIRECTION vector 
{ curr_light->direction = $2; 


$3; } 


mi_vector_normalize(&curr_light->direction) ; 


light_map |= 4; } 
ENERGY floating floating floating 
{ curr_light->energy.r = $2; 
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curr_light->energy.g = $3; 
curr_light->energy.b = $4; } 
EXPONENT floating 
{ curr_light->exponent 
CAUSTIC PHOTONS T_INTEGER 
{ curr_light->caustic_store_photons = 


$2; } 


curr_light->caustic_emit_photons = 0; } 


CAUSTIC PHOTONS T_INTEGER T_INTEGER 
{ curr_light->caustic_store_photons = 


$3 ; 


$3 ; 


curr_light->caustic_emit_photons = $4; } 


GLOBILLUM PHOTONS T_INTEGER 


{ curr_light->global_store_photons = $3; 


curr_light->global_emit_photons = 0; 
GLOBILLUM PHOTONS T_INTEGER T_INTEGER 


{ curr_light->global_store_photons = $3; 


curr_light->global_emit_photons = $4; } 


RECTANGLE vector vector light_samples 


{ curr_light->area = miLIGHT_RECTANGLE; 
curr_light->primitive.rectangle.edge_u 
curr_light->primitive.rectangle.edge_v 


DISC vector floating light_samples 
{ curr_light->area = miLIGHT_DISC; 
curr_light->primitive.disc.normal 
curr_light->primitive.disc.radius 
SPHERE floating light_samples 
{ curr_light->area = miLIGHT_SPHERE; 
curr_light->primitive.sphere.radius 
CYLINDER vector floating light_samples 
{ curr_light->area = miLIGHT_CYLINDER; 
curr_light->primitive.cylinder.axis 


curr_light->primitive.cylinder.radius 


OBJECT symbol light_samples 
{ curr_light->area = miLIGHT_OBJECT; 
curr_light->primitive.object.object 
mi_api_name_lookup($2); } 
USER light_samples 
{ curr_light->area = miLIGHT_USER; } 
RECTANGLE 
{ curr_light->area = miLIGHT_NONE; } 
DISC 
{ curr_light->area = miLIGHT_NONE; } 
SPHERE 
{ curr_light->area = miLIGHT_NONE; } 
CYLINDER 
{ curr_light->area = miLIGHT_NONE; } 
SPREAD floating 
{ curr_light->spread = $2; 
light_map |= 32; } 
SHADOWMAP RESOLUTION T_INTEGER 


{ curr_light->shadowmap_resolution = $3; } 


SHADOWMAP SOFTNESS floating 
{ curr_light->shadowmap_softness = $3; 
SHADOWMAP SAMPLES T_INTEGER 
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$2; 
$3; } 
$2; 
$3; } 
$2; } 
$2; 
$3; } 
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light_samples 


{ curr_light->shadowmap_samples = $3; } 


SHADOWMAP FILTER filter_type 
{ curr_light->shmap.filter 


curr_light->shmap.filter_u 
curr_light->shmap.filter_v 
SHADOWMAP FILTER filter_type floating 


{ curr_light->shmap.filter 


curr_light->shmap.filter_u 
curr_light->shmap.filter_v 


SHADOWMAP FILTER filter_type floating floating 


{ curr_light->shmap.filter 


curr_light->shmap.filter_u 
curr_light->shmap.filter_v = 


SHADOWMAP ACCURACY floating 


{ curr_light->shmap. accuracy 


SHADOWMAP ALPHA 

{ curr_light->shmap.type 
SHADOWMAP COLOR 

{ curr_light->shmap.type 
SHADOWMAP FILE_ T_STRING 


{ mi_scene_delete(curr_light->shadowmap_file) ; 


0.02 + 
$3 ; 

$4; } 
$3; 

$4 ; 


$5; } 


> a 


strcpy((char *)mi_scene_create( 


&curr_light->shadowmap_file, 
miSCENE_STRING, strlen($3)+1), $3); 
mi_db_unpin(curr_light->shadowmap_file) ; 


mi_mem_release($3); } 
VISIBLE 


{ curr_light->visible = miTRUE; } 


VISIBLE boolean 

{ curr_light->visible 
TAG T_INTEGER 

{ curr_light->label = $2; } 


$2; 


{ curr_datatag = &curr_light->userdata; } 


data 


T_INTEGER 
{ curr_light->samples_u 
curr_light->samples_v 
T_INTEGER T_INTEGER 
{ curr_light->samples_u 
curr_light->samples_v 
T_INTEGER T_INTEGER T_INTEGER 
{ curr_light->samples_u 
curr_light->samples_v 
curr_light->low_level 


T_INTEGER T_INTEGER T_INTEGER T_INTEGER T_INTEGER 


{ curr_light->samples_u 
curr_light->samples_v 
curr_light->low_level 
curr_light->low_samples_u 
curr_light->low_samples_v 


} 


$1; 
$2; } 


= $i; 


$2; 
$3; } 


= $1; 


= $2; 


$3; 
$4; 
$5; } 
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/*----------------------------------------------------------------- 
* material 
*#---------------------------------------------------- ---- --- = - - = ------- = * / 
material : MATERIAL symbol 


mtl_shader 


mtl_flags 


mtl_flag 


mtl_args 


mtl_arg 


{ curr_mtl = mi_api_material_begin($2) ; 
have_d = have_s = have_v = have_e = have_c = 
have_p = have_pv = have_lm = have_hw = 0; } 
mtl_flags 
mtl_shader 
mtl_args 
END MATERIAL 
{ mi_api_material_end(); } 


function List 
{ curr_mtl->shader = $1; } 


mtl_flag mtl_flags 


: NOCONTOUR 


{ mi_api_warning ( 
"obsolete \"nocontour\" flag ignored"); } 
OPAQUE_ 
{ curr_mtl->opaque = miTRUE; } 


mtl_arg mtl_args 


: DISPLACE 


{ mi_api_function_delete(&curr_mtl->displace); } 
DISPLACE function_list 
{ if (!have_d++) 
mi_api_function_delete(&curr_mtl->displace) ; 
curr_mtl->displace = $2; } 
SHADOW 
{ mi_api_function_delete(&curr_mtl->shadow); } 
SHADOW function_list 
{ if (!have_s++) 
mi_api_function_delete(&curr_mt1l->shadow) ; 
curr_mtl->shadow = $2; } 
VOLUME 
{ mi_api_function_delete(&curr_mtl->volume); } 
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VOLUME function_list 
{ if ('thave_v++) 
mi_api_function_delete(&curr_mt1l->volume) ; 
curr_mtl->volume = $2; } 
ENVIRONMENT 
{ mi_api_function_delete(&curr_mtl->environment); } 
ENVIRONMENT function_list 
{ if (!have_e++) 
mi_api_function_delete(&curr_mtl->environment) ; 
curr_mtl->environment = $2; } 
CONTOUR 
{ mi_api_function_delete(&curr_mtl->contour); } 
CONTOUR function_list 
{ if (!have_c++) 
mi_api_function_delete(&curr_mtl->contour) ; 
curr_mtl->contour = $2; } 
PHOTON 
{ mi_api_function_delete(&curr_mtl->photon); } 
PHOTON function_list 
{ if (!have_pt++) 
mi_api_function_delete(&curr_mt1l->photon) ; 
curr_mtl->photon = $2; } 
PHOTONVOL 
{ mi_api_function_delete(&curr_mtl->photonvol); } 
PHOTONVOL function_list 
{ if (!have_pvt++) 
mi_api_function_delete(&curr_mtl->photonvol) ; 
curr_mtl->photonvol = $2; } 
LIGHTMAP 
{ mi_api_function_delete(&curr_mtl->lightmap); } 
LIGHTMAP function_list 
{ if (!have_1lm++) 
mi_api_function_delete(&curr_mtl->lightmap) ; 
curr_mtl->lightmap = $2; } 


/*------------------ - - - - - - ee 
* object 
*#------------------------------------- -- - - - - - - - - - - - = * / 

object : OBJECT opt_symbol 

{ curr_obj = mi_api_object_begin($2); } 
obj_flags 
object_body 
END OBJECT 
{ mi_api_object_end(); } 
obj_flags 


obj_flags obj_flag 
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obj_flag 


: VISIBLE 


{ curr_obj->visible 
VISIBLE boolean 
{ curr_obj->visible 
SHADOW 
{ curr_obj->shadow 
SHADOW boolean 
{ curr_obj->shadow 
SHADOW T_INTEGER 
{ curr_obj->shadow 
SHADOWMAP 
{ curr_obj->shadowmap 
SHADOWMAP boolean 
{ curr_obj->shadowmap 
TRACE 
{ curr_obj->reflection 
curr_obj->refraction 
curr_obj->finalgather 
TRACE boolean 
{ curr_obj->reflection 
curr_obj->refraction 
curr_obj->finalgather 
REFLECTION T_INTEGER 
{ curr_obj->reflection 
REFRACTION T_INTEGER 
{ curr_obj->refraction 
TRANSPARENCY T_INTEGER 


{ curr_obj->transparency 


FACE FRONT 

{ curr_obj->face 
FACE BACK 

{ curr_obj->face 
FACE BOTH 

{ curr_obj->face 
SELECT 

{ curr_obj->select 
SELECT boolean 

{ curr_obj->select 
TAGGED 


{ curr_obj->mtl_is_label 


TAGGED boolean 


{ curr_obj->mtl_is_label 


CAUSTIC 

{ curr_obj->caustic 
CAUSTIC boolean 

{ curr_obj->caustic 


= miTRUE; } 
= $2; } 

= 0x03; } 

= $2 7? 0x03 : 
= ($2 & 0x03); } 
= miTRUE; } 


= $2; } 


= 0x03; } 


= $2 ? 0x08 : 
= ($2 & 0x03); } 
= ($2 & 0x03); } 
= ($2 & 0x03); } 


sat rf? } 


ll 
A 
No 
WY 


= 0x03; 


if (!$2) curr_obj->caustic |= 0x10; } 


CAUSTIC T_INTEGER 
{ curr_obj->caustic 
curr_obj->caustic 
GLOBILLUM 
{ curr_obj->globillum 
GLOBILLUM boolean 


&= 0x10; 


= ($2 & 0x03); } 


= 3; } 
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0x02; } 


0x02; } 
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object_body 


{ curr_obj->globillum 


if (!$2) curr_obj->globillum |= 0x10; } 


GLOBILLUM T_INTEGER 
{ curr_obj->globillum 
curr_obj->globillum 

FINALGATHER boolean 


&= 0x03; 


&= O0xi0; 
($2 & 0x03); } 


{ curr_obj->finalgather &= 0x03; 


if (!$2) curr_obj->finalgather 


FINALGATHER T_INTEGER 


{ curr_obj->finalgather &= 0x10; 


curr_obj->finalgather |= ($2 & 0x03); } 


FINALGATHER FILE_ map_list 


{ mi_api_taglist_reset (&curr_obj->finalgather_file, 


TAG T_INTEGER 


$ 


3)3. + 


{ curr_obj->label = $2; } 


{ curr_datatag = &curr_obj->userdata; } 


data 
transform 


{ mi_api_object_matrix($1); } 


MAX_ DISPLACE floating 


{ curr_obj->maxdisplace 


RAY OFFSET floating 
{curr_obj->ray_offset 
BOX vector vector 
{ curr_obj->bbox_min 
curr_obj->bbox_max 
BOX 
{ curr_obj->bbox_min 
curr_obj->bbox_max 
MOTION BOX vector vector 
{ curr_obj->bbox_min_ 
curr_obj->bbox_max_ 
MOTION BOX 
{ curr_obj->bbox_min_ 
curr_obj->bbox_max_ 
SAMPLES T_INTEGER 


{ curr_obj->min_samples = 
curr_obj->max_samples 


m 
m 


m 
m 


SAMPLES T_INTEGER T_INTEGER 


{ curr_obj->min_samples = 
curr_obj->max_samples 


VOLUME GROUP T_INTEGER 


$ 
$ 


= $3; } 
$33 3 


2% 
a3: 5 


nullvec; 
nullvec; } 


$3; 


= $4; } 


{ curr_obj->volume_id = 


: bases_and_groups 


FILE_ T_STRING 


nullvec; 
nullvec; } 


ll 
A 
NO 
gid 


{ mi_api_object_file($2); } 


hair_object 
trilist_object 


|= Oxi0O; } 
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bases_and_groups: 


basis 


rational 


basis_matrix 


group 


merge_option 


vector_list 


vertex_list 


. 
’ 


basis 
group 


: BASIS 


BASIS 


BASIS 


BASIS 


BASIS 
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bases_and_groups 
bases_and_groups 


symbol rational MATRIX T_INTEGER T_INTEGER basis_matrix 
{ mi_api_basis_add($2, $3, miBASIS_MATRIX, $5,$6,$7); } 
symbol rational BEZIER T_INTEGER 

{ mi_api_basis_add($2, $3, miBASIS_BEZIER, $5, 0, 0); } 
symbol rational TAYLOR T_INTEGER 

{ mi_api_basis_add($2, $3, miBASIS_TAYLOR, $5, 0, 0); } 
symbol rational BSPLINE T_INTEGER 

{ mi_api_basis_add($2, $3, miBASIS_BSPLINE, $5, 0, 0);} 
symbol rational CARDINAL 

{ mi_api_basis_add($2, $3, miBASIS_CARDINAL, 3, 0, 0);} 


{ $$ = miFALSE; } 


RATIONAL 


basis_ 


: GROUP 


{ $$ = miTRUE; } 


{ $$ mi_api_dlist_create(miDLIST_GEOSCALAR); } 
matrix floating 
{ miGeoScalar s=$2; mi_api_dlist_add($1, &s); $$=$1; } 


opt_symbol merge_option 
{ mi_api_object_group_begin($3) ; 
mi_mem_release($2); } 


vector_list 
vertex_list 
geometry_list 
END GROUP 


MERGE 


{ mi_api_object_group_end(); } 


{ $$ = 0.0; } 
floating 
{ $$ = $2; } 


vector_list geovector 


{ mi_api_geovector_xyz_add(&$2); } 


vertex_list vertex 
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vertex 


n_vector 


d_vector 


m_vector_list 


t_vector_list 


u_vector_list 


vertex_flag 


: V T_INTEGER 


{ mi_api_vertex_add($2); } 
n_vector 
d_vector 
t_vector_list 
m_vector_list 
u_vector_list 
vertex_flag 


N T_INTEGER 
{ mi_api_vertex_normal_add($2); } 


D T_INTEGER T_INTEGER 
{ mi_api_vertex_deriv_add($2, $3); } 
D T_INTEGER T_INTEGER T_INTEGER 
{ mi_api_vertex_deriv2_add($2, $3, $4); } 
D T_INTEGER T_INTEGER T_INTEGER T_INTEGER T_INTEGER 
{ mi_api_vertex_deriv_add($2, $3); 
mi_api_vertex_deriv2_add($4, $5, $6); } 


m_vector_list M T_INTEGER 
{ mi_api_vertex_motion_add($3); } 


t_vector_list T T_INTEGER 
{ mi_api_vertex_tex_add($3, -1, -1); } 
t_vector_list T T_INTEGER T_INTEGER T_INTEGER 
{ mi_api_vertex_tex_add($3, $4, $5); } 


u_vector_list U T_INTEGER 
{ mi_api_vertex_user_add($3); } 


CUSP 

{ mi_api_vertex_flags_add(miAPI_V_CUSP, 0, 1.f); } 
CUSP LEVEL T_INTEGER 

{ mi_api_vertex_flags_add(miAPI_V_CUSP, $3, 1.f); } 
CONIC 

{ mi_api_vertex_flags_add(miAPI_V_CONIC, 0, 1.f); } 
CONIC LEVEL T_INTEGER 

{ mi_api_vertex_flags_add(miAPI_V_CONIC, $3, 1.f); } 
CORNER 

{ mi_api_vertex_flags_add(miAPI_V_CORNER, 0, 1.f); } 
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CORNER LEVEL T_INTEGER 

{ mi_api_vertex_flags_add(miAPI_V_CORNER, $3, 1.f); } 
| DART 
{ mi_api_vertex_flags_add(miAPI_V_DART, 0, 0.f); } 


geometry_list 
| geometry_list geometry 


geometry : polygon 

curve 
spacecurve 
surface 
subdivsurf 
connection 
approximation 


/* polygons */ 


polygon : CP opt_symbol 
{ mi_api_poly_begin(1, $2); } 
poly_indices 
{ mi_api_poly_end(); } 
| P opt_symbol 
{ mi_api_poly_begin(0, $2); } 
poly_indices 
{ mi_api_poly_end(); } 
| STRIP opt_symbol 
{ mi_api_poly_begin(2, $2); } 
strip_indices 
{ mi_api_poly_end(); } 
| FAN opt_symbol 
{ mi_api_poly_begin(3, $2); } 
strip_indices 
{ mi_api_poly_end(); } 


poly_indices 


T_INTEGER 

{ mi_api_poly_index_add($1); } 
poly_indices 
| HOLE 

{ mi_api_poly_hole_add(); } 
poly_indices 


strip_indices 
| T_INTEGER 
{ mi_api_poly_index_add($1); } 
strip_indices 
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h_vertex_ref_seq: h_vertex_ref 
| h_vertex_ref_seq h_vertex_ref 


. 
’ 


h_vertex_ref : T_INTEGER 
{ mi_api_vertex_ref_add($1, (double)1.0); } 
| T_INTEGER T_FLOAT 
{ mi_api_vertex_ref_add($1, $2); } 
| T_INTEGER W floating 
{ mi_api_vertex_ref_add($1, $3); } 


para_list : T_FLOAT 

{ miDlist *dlp =mi_api_dlist_create(miDLIST_GEOSCALAR) ; 
miGeoScalar s = $1; /* $1 is a double */ 
mi_api_dlist_add(dlp, &s); 
$$ = dlp; } 

| para_list T_FLOAT 

{ miGeoScalar s = $2; /* $2 is a double */ 
mi_api_dlist_add($1, &s); 
$$ = $1; } 


/* curves and space curves */ 


curve : CURVE symbol rational symbol 
{ mi_api_curve_begin($2, $4, $3); } 
para_list h_vertex_ref_seq curve_spec 
{ mi_api_curve_end($6); } 


curve_spec 
| SPECIAL curve_special_list 


. 
bf 


curve_special_list 
: Ccurve_special 
| curve_special_list curve_special 


curve_special : T_INTEGER 
{ mi_api_curve_specpnt ($1, -1); } 
| T_INTEGER MAPSTO T_INTEGER 
{ mi_api_curve_specpnt($1, $3); } 


spacecurve : SPACE CURVE symbol 
{ mi_api_spacecurve_begin($3); } 
spcurve_list 
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{ mi_api_spacecurve_end(); } 


spcurve_list : symbol floating floating 

{ miGeoRange r; 
r.min = $2; 
r.max = $3; 
mi_api_spacecurve_curveseg(miTRUE, $1, &r); } 

| spcurve_list symbol floating floating 

{ miGeoRange r; 
r.min = $3; 
r.max = $4; 
mi_api_spacecurve_curveseg(miFALSE, $2, &r); } 


/* free-form surfaces */ 


surface : SURFACE symbol mtl_or_label 
{ mi_api_surface_begin($2, $3); } 
rational symbol floating floating para_list 
{ mi_api_surface_params(miU, $6, $7, $8, $9, $5); } 
rational symbol floating floating para_list 
{ mi_api_surface_params(miV, $12, $13, $14, $15, $11) ;} 
h_vertex_ref_seq 
tex_surf_list 
surf_spec_list 
{ mi_api_surface_end(); } 


mtl_or_label : symbol 
$3 = $15.3 
| T_INTEGER 
{ $$ = (char *)(miIntptr)$1; } 


tex_surf_list 
| tex_surf_list tex_surf 


tex_surf : opt_volume_flag opt_vector_flag TEXTURE 
rational symbol para_list 
rational symbol para_list 
{ mi_api_surface_texture_begin( 
$1, $2, $5, $6, $4, $8, $9, $7); } 


h_vertex_ref_seq 


| DERIVATIVE 

{ mi_api_surface_derivative(1); } 
| DERIVATIVE T_INTEGER 

{ mi_api_surface_derivative($2); } 
| DERIVATIVE T_INTEGER T_INTEGER 

{ mi_api_surface_derivative ($2) ; 
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opt_volume_flag : 


opt_vector_flag : 


surf_spec_list 


surf_spec 


trim_spec_list 


hole_spec_list 


special_spec_list 


mi_api_surface_derivative($3); } 


{ $$ = miFALSE; } 
VOLUME 

{ $$ = miTRUE; } 

{ $$ = miFALSE; } 
VECTOR 

{ $$ = miTRUE; } 


surf_spec_list surf_spec 


: TRIM trim_spec_list 


HOLE hole_spec_list 
SPECIAL 

{ newloop = miTRUE; } 
special_spec_list 


symbol floating floating 
{ miGeoRange r; 
r.min = $2; 
r.max = $3; 
mi_api_surface_curveseg(miTRUE, miCURVE_TRIM,$1,&r) ;} 
trim_spec_list symbol floating floating 
{ miGeoRange r; 
r.min = $3; 
r.max = $4; 
mi_api_surface_curveseg(miFALSE,miCURVE_TRIM,$2, &r) ; } 


symbol floating floating 
{ miGeoRange r; 
r.min = $2; 
r.max = $3; 
mi_api_surface_curveseg(miTRUE,miCURVE_HOLE,$1,&r); } 
hole_spec_list symbol floating floating 
{ miGeoRange r; 
r.min = $3; 
r.max = $4; 
mi_api_surface_curveseg (miFALSE,miCURVE_HOLE, $2, &r) ; } 


special_spec 
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special_spec 


connection 


special_spec_list special_spec 


: T_INTEGER 


{ mi_api_surface_specpnt($1, -1); } 


T_INTEGER MAPSTO T_INTEGER 


{ mi_api_surface_specpnt($1, $3); } 


symbol floating floating 
{ miGeoRange r; 


r.min 


$ 


re 


r.max = $3; 


mi_api_surface_curveseg(newloop, 


newloop 


: CONNECT 


symbol symbol floating floating 
symbol symbol floating floating 


miFALSE; } 


{ miGeoRange ci, c2; 


ci.min 
ci.max 


c2.min = 


c2.max 
mi_api 


/* subdivision surfaces */ 


subdivsurf 


sds_surf 


sds_specs 


sds_spec 


$4; 
$5 ; 
$8 ; 
$9; 
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miCURVE_SPECIAL, $1, &r); 


object_group_connection($2,$3,&c1,$6,$7,&c2) ;} 


: SUBDIVISION SURFACE 
{ memset (&subdiv_opt, 0, sizeof(subdiv_opt)); } 


sds_surf 
sds_base_faces 
derivatives 


END SUBDIVISION SURFACE 


{ mi_api_subdivsurf_end(); } 


symbol sds_specs 
{ mi_api_subdivsurf_begin_x($1, &subdiv_opt); } 


sds_specs sds_spec 


no_basetris 
no_hiratris 
no_basequads 
no_hiraquads 
no_vertices 


: POLYGON T_INTEGER T_INTEGER T_INTEGER T_INTEGER 
{ subdiv_opt. 
subdiv_opt. 
subdiv_opt. 
subdiv_opt. 
subdiv_opt. 


$2; 
$3 ; 
$4; 
$5; 
0; } 
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texspace 


texspace_nxt 


derivatives 


derivative 


sds_base_faces 


sds_base_face 


base_data 


base_spec 


TEXTURE SPACE 
{ texspace_idx = 0; } 
>[? texspace ’]’ 


{ mi_api_subdivsurf_texspace(subdiv_texspace, 
texspace_idx); } 


: FACE texspace_nxt 


{ subdiv_texspace[texspace_idxt++] .face 
SUBDIVISION texspace_nxt 
{ subdiv_texspace [texspace_idx++] .face 


2 2 
5) 


>,’ texspace 


derivatives derivative 


: DERIVATIVE T_INTEGER 


{ mi_api_subdivsurf_derivative($2, 0); } 
DERIVATIVE T_INTEGER SPACE T_INTEGER 
{ mi_api_subdivsurf_derivative($2, $4); } 


sds_base_faces sds_base_face 


: P opt_symbol sds_indices 


{ mi_api_subdivsurf_baseface() ; 
mi_api_subdivsurf_mtl(-1, $2); } 
base_data 


base_spec base_data 


af? 

{ mi_api_subdivsurf_push() ; 

mi_api_subdivsurf_subdivide(-1); } 

hira_data ’}’ 

{ mi_api_subdivsurf_pop(); } 
CREASE T_INTEGER sds_creaseflags 

{ mi_api_subdivsurf_crease(-1, $2); } 
TRIM T_INTEGER 

{ mi_api_subdivsurf_trim(-1, $2); } 


miTRUE; } 


miFALSE; } 


W9O7 
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hira_data 
| hira_spec hira_data 


hira_spec : MATERIAL T_INTEGER symbol 
{ mi_api_subdivsurf_mt1($2, $3); } 
MATERIAL T_INTEGER T_INTEGER 
{ mi_api_subdivsurf_mtl_tag($2, $3); } 
| DETAIL T_INTEGER sds_indices 
{ mi_api_subdivsurf_detail($2); } 
| CREASE T_INTEGER T_INTEGER sds_creaseflags 
{ mi_api_subdivsurf_crease($2, $3); } 
| TRIM T_INTEGER T_INTEGER 
{ mi_api_subdivsurf_trim($2, $3); } 
| CHILD T_INTEGER ’{?’ 
{ mi_api_subdivsurf_push() ; 
mi_api_subdivsurf_subdivide($2); } 
hira_data ’}?’ 
{ mi_api_subdivsurf_pop(); } 


sds_indices 


T_INTEGER 
{ mi_api_subdivsurf_index($1); } 
sds_indices 


sds_creaseflags 
| floating 
{ mi_api_subdivsurf_crease_edge($1); } 
sds_creaseflags 


/* hairs */ 


hair_object : HAIR 
{ hair = mi_api_hair_begin(); } 
hair_options 
SCALAR ’[’? T_INTEGER ’]? 
{ hair_index = 0; 
hair_scalars = mi_api_hair_scalars_begin($6); } 
hair_scalars 
{ mi_api_hair_scalars_end(hair_index); } 
HAIR ’[’ T_INTEGER ’]’ 
{ mi_api_hair_hairs_begin($13); } 
hair_hairs 
{ mi_api_hair_hairs_end() ; 
mi_api_hair_end(); } 
END HAIR 


hair_options : hair_option hair_options 
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hair_option : MATERIAL symbol 
{ hair->material = mi_api_material_lookup($2); } 
RADIUS floating 
{ hair->radius = $2; } 
| APPROXIMATE T_INTEGER 
{ hair->approx = $2; } 
| DEGREE T_INTEGER 
{ hair->degree = $2; } 
| MAX_ SIZE T_INTEGER 


{ hair->space_max_size = $3; } 
| MAX_ DEPTH T_INTEGER 
{ hair->space_max_depth = $3; } 


| HAIR N 
1 mi_api_ heir info(0, *n*), 333-5 
| HAIR M T_INTEGER 
{ mi_api_hair_info(0O, ’m’, 3*$3); } 
| HAIR T T_INTEGER 
Aomiic epi hair anfo(O5 1"? S8)s0 5 
HAIR RADIUS 
1 Miapi_hair_info(O,: °r%4. 1); } 
| HAIR U T_INTEGER 
{ mi_api_hair_info(0,/ *u? , $3); } 
| VERTEX N 
+ Bivapl bais Ste Cl? a? S757 5 
| VERTEX M T_INTEGER 
{ mi_api_hair_info(1, ’m’, 3*$3); } 
| VERTEX T T_INTEGER 
+, Wicapi hair intotl, °t*, $3)% F 
VERTEX RADIUS 
1 Miceli Rais Antet] ,' ?¢%5 1)3 + 
| VERTEX U T_INTEGER 
1, Mi ep Mate Intott (Pury B3)4 3 


hair_scalars 
| hair_scalars floating 
{ if (hair_index < hair->no_scalars) 
hair_scalars[hair_index] = $2; 
hair_indext++; } 


hair_hairs 
| hair_hairs T_INTEGER 
{ mi_api_hair_hairs_add($2); } 


/* trilists */ 


trilist_object : TRILIST 
{ memset (&tlcont, 0, sizeof (tlcont)) ; 
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tlcont.sizeof_vertext++; } 
VECTOR ’[’ T_INTEGER ’]’ 
VERTEX ’[’? T_INTEGER ’]’ P 
tl_specs 
TRIANGLE ’[’ T_INTEGER ’]’ 


{ tlbox = mi_api_trilist_begin(&tlcont, 


a: oy 


$5, $9, $15); 
tlvec = tlbox->vectors; 
tlvert = miBOX_GET_VERTICES (tlbox) ; 
tlvec_idx = tlvert_idx = tl_ind = 0; 
tl_nvec = $5; 
tl_nvert = $9 * tlcont.sizeof_vertex; 
tl_nind = tlbox->mtl_is_label 7? 4 : 

?>{? tl_vectors 1}? 


‘[? tl vertices *])’ 
*[? tl_trianglies. *]? 
END TRILIST 
{ mi_api_trilist_end(); } 
tl_approx 
TRILIST VERTEX T_INTEGER P 
{ memset (&plinfo, 0, sizeof(plinfo)); 
plinfo.line_size = 3; } 
pl_specs 
TRIANGLE T_INTEGER pl_border 
{ miUint no_prims = $8 + $9; 
miUint no_plist = $9 72: 1; 


plbox = mi_api_primlist_begin(&plinfo, 
$3, no_plist, no_prims * 3, 
no_prims, 0, no_prims) ; 


if ($9) 


mi_api_primlist_border(1, $9); 
miBOX_VERTEX_LINES (plbox) ; 


pllines 
plprims = miBOX_PRIMS(plbox) ; 
plmtls = miBOX_MATERIALS(plbox) ; 


*plprims++ = miSCENE_PRIMLIST_MAKE_CODE( 
miSCENE_PRIM_TRI, $8 * 3); 
mi_api_primlist_dimensions(pl_texo, pl_uso) ; 


tl_nind = plbox->mtl_is_label 7? 4 : 

tl_ind = 0; pl_no_prims = $8; } 
pl_lines 
pl_prims 5! 
pl_borderprims 
pl_topology 
END TRILIST 

{ miUint no_prims = $8 + $9; 

miUint no_plist = $9 72: 1; 

mi_api_primlist_end() ; 

if (plprims != miBOX_PRIMS(plbox)+ 

no_prims*3+no_plist) 


3; 
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/* new in 3.4 */ 


mi_api_error("wrong number of triangles"); 
if (pllines != miBOX_VERTEX_LINES(plbox) + $3 * 


plinfo.line_size) 


mi_api_error("wrong number of scalars"); } 
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tl_approx 


/* new trilists 3.4 */ 


pl_topology 


TOPOLOGY 
{ pltop = mi_mem_allocate(sizeof(miUint) * 
plbox->no_prims*3) ; 
cur_pltop = pltop; } 
pl_top 
{ mi_api_primlist_topology(pltop) ; 
mi_mem_release(pltop); } 


pl_top : [pl top: eecia. *) 
| INTEGER 
{ ctx->read_integer = plbox->no_prims*3; 
ctx->ri_buf = (int*)pltop; } 
T_VECTOR 


pl_top_ascii : 
| pl_top_ascii T_INTEGER 
{ *cur_pltop++ = $2; } 


pl_border 
{ $$ = 0; } 
| BORDER T_INTEGER 
1 So & S252% 
pl_lines : SCALAR 


{ ctx->read_integer = plinfo.line_size * 
miBOX_NO_VTXLINES (plbox) ; 
ctx->ri_buf = (int*)pllines; } 
T_VECTOR 
{ pllines += plinfo.line_size * 
miBOX_NO_VTXLINES(plbox) ; } 
| *L? ploeecii lines *]* * 


pl_ascii_lines 
| pl_ascii_lines floating 
{ *pllines++ = $2; } 


pl_borderprims : 
| { *plprims++ = miSCENE_PRIMLIST_MAKE_CODE( 
miSCENE_PRIM_TRI, 
plbox->no_border_prims * 3); 
pl_no_prims = plbox->no_border_prinms; 
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pl_prims 


plitricmtl 


pl_tri_index 


pl_tri_ascindex :; 


pl_specs 


tex_dims 
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} pl_prims 


?[? symbol T_INTEGER T_INTEGER T_INTEGER 
{ *plmtls++ = mi_api_material_lookup($2) ; 
*plprims++ = $3; *plprimst++ = $4; 
*plprimst+ = $5; } 
pl. tri.metl 
>]? 


pl_tri_index 


pl_tri_mtl opt_symbol T_INTEGER T_INTEGER T_INTEGER 


{ *plmtls++ = ($2) ? mi_api_material_lookup ($2) 
* (plmtls-2) ; 
*plprims++ = $3; *plprimst++ = $4; 
*xplprimst++ = $5; } 


INTEGER 
{ if (tl_nind != 4) 
mi_api_error("binary triangles/no " 
"tagged mode") ; 
ctx->read_integer = pl_no_prims*3; 
ctx->ri_buf = (int*)plprims; } 
T_VECTOR 
{ plprims += pl_no_prims*3; } 
INTEGER 
{ ctx->read_integer = pl_no_prims; 
ctx->ri_buf = (int*)plmtls; } 
T_VECTOR 
{ plmtls += pl_no_prims; } 
?[? pl_tri_ascindex ’]’ 


pl_tri_ascindex T_INTEGER 
{ if (tl_nind == 4 && !(tl_ind++ & 3)) 
*plmtls++ = $2; 
else 
*plprimst++ = $2; } 


pl_spec pl_specs 


tex_dims T_INTEGER 
{ plinfo.line_size += $2; 
pl_texo[plinfo.no_textures] = $2; 
plinfo.no_texturest++; } 
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us_dims : 
| us_dims T_INTEGER 
{ plinfo.line_size += $2; 
pl_uso[plinfo.no_users] = $2; 
plinfo.no_users++; } 
pl_spec : N 


{ plinfo.normal_offset = plinfo.line_size; 
plinfo.line_size += 3; } 


{ plinfo.derivs_offset = plinfo.line_size; 
plinfo.line_size += 6; } 


{ plinfo.derivs2_offset = plinfo.line_size; 
plinfo.line_size += 9; } 
| M opt_size 
{ plinfo.motion_offset = plinfo.line_size; 
plinfo.no_motions = $2; 
plinfo.line_size += $2 * 3; } 
| B opt_size 
{ plinfo.bump_offset = plinfo.line_size; 
plinfo.no_bumps = $2; 
plinfo.line_size += $2 * 3; } 


a 
{ plinfo.texture_offset = plinfo.line_size; } 
tex_dims 
| U 
{ plinfo.user_offset = plinfo.line_size; } 
us_dims 


/* trilists 3.3 */ 


tl_vectors 
| tl_vectors vector 
{ if (tlvec_idx < tl_nvec) 
tlvec[tlvec_idx++] = $2; } 


tl_vertices 
| tl_vertices T_INTEGER 
{ if (tlvert_idx < tl_nvert) 
tlvert [tlvert_idxt++] = $2; } 


tl_triangles : symbol T_INTEGER T_INTEGER T_INTEGER 
{ tl_indbuf [0] $2: tl_indbuf[1] = $3; 
tl_indbuf [2] $4; 
mi_api_trilist_triangle($1, tl_indbuf); } 
tL Er. wel 
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EL ert Et 


tl_tri_index 


tl_specs 


tl_spec 


opt_size 


tl_tri_index 
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tl_tri_mtl opt_symbol T_INTEGER T_INTEGER T_INTEGER 
{ tl_indbuf [0] = $3; tl_indbuf[1] = $4; 
tl_indbuf [2] = $5; 


mi_api_trilist_triangle($2, tl_indbuf); } 


tl_tri_index T_INTEGER 
{ tl_indbuf [tl_ind++] = $2; 


ft Cet 


5S 


_ind == tl_nind) { 
mi_api_trilist_triangles(tl_indbuf, 1); 
tl_ind = 0; 


tl_spec tl_specs 


D2 


{ tlcont 
tlcont 


{ tlcont 


tloont. 


{ tlcont 


tlcont. 
opt_size 


{ tlcont 
tlcont 


tlcont. 
opt_size 


{ tlcont 
tlcont 
tlcont 


opt_size 


{ tlcont 
tlcont 


tlcont. 
opt_size 


{ tlcont 
tLlcoont 


tlcont. 


{ $$ = 1 


T_INTEGER 


.normal_offset = tlcont.sizeof_vertex; 
.sizeof_vertex++; } 


.derivs_offset = tlcont.sizeof_vertex; 
sizeof_vertext++; } 


.derivs2_offset = tlcont.sizeof_vertex; 
sizeof_vertext++; } 


.motion_offset = tlcont.sizeof_vertex; 
.no_motions = $2; 
sizeof_vertex += $2; } 


.texture_offset = tlcont.sizeof_vertex; 
.no_textures = $2; 
.sizeof_vertex += $2; } 


-bump_offset = tlcont.sizeof_vertex; 
.no_bumps = $2; 
sizeof_vertex += $2; } 


.user_offset = tlcont.sizeof_vertex; 


.no_users = $2; 
sizeof_vertex += $2; } 


- 
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{ $$ = $1; } 
tl_approx 
| approximation 
/*----------------------------- -- - 
* approximations (in objects and options) 
*#--------------------------------------------- -- ----- -- -- - = - - 5 = * / 
approximation =: { miAPPROX_DEFAULT(approx); } 


approx_flags approx_body 


approx_flags : 
| approx_flag approx_flags 


approx_flag : VISIBLE 

{ approx.flag |= miAPPROX_FLAG_VISIBLE; } 
| TRACE 

{ approx.flag |= miAPPROX_FLAG_TRACE; } 
| SHADOW 

{ approx.flag |= miAPPROX_FLAG_SHADOW; } 
| CAUSTIC 

{ approx.flag |= miAPPROX_FLAG_CAUSTIC; } 
| GLOBILLUM 


{ approx.flag |= miAPPROX_FLAG_GLOBILLUM; } 


approx_body : APPROXIMATE SURFACE s_approx_tech s_approx_names 
APPROXIMATE SUBDIVISION SURFACE 
C_approx_tech sds_approx_names 
APPROXIMATE DISPLACE s_approx_tech d_approx_names 
| APPROXIMATE CURVE C_approx_tech c_approx_names 
| APPROXIMATE SPACE CURVE 
C_approx_tech spc_approx_names 
APPROXIMATE TRIM C_approx_tech t_approx_names 
| APPROXIMATE S_approx_tech 
{ mi_api_poly_approx(xapprox); } 
APPROXIMATE TRILIST s_approx_tech 
{ mi_api_trilist_approx(&approx); } 


S_approx_tech : s_approx_params 
{ approx.subdiv[miMIN] = 0; 
approx. subdiv [miMAX] 5} 
approx.max = miHUGE_INT; 
if (approx.style == miAPPROX_STYLE_FINE | | 
approx.style == miAPPROX_STYLE_FINE_NO_SMOOTHING) 
approx.subdiv[miMAX] = 7; } 
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C_approx_tech 


S_approx_params 


C_approx_params 


S_approx_param 


S_approx_params T_INTEGER T_INTEGER 
{ approx.subdiv [miMIN] $2; 
approx. subdiv [miMAX] $3; 
approx .max miHUGE_INT; } 
S_approx_params MAX_ T_INTEGER 
{ approx.subdiv [miMIN] 0; 
approx.subdiv[miMAX] = 5; 
approx .max = $3; 


if (approx.style == miAPPROX_STYLE_FINE | | 
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approx.style == miAPPROX_STYLE_FINE_NO_SMOOTHING) 


approx.subdiv[miMAX] = 7; } 


S_approx_params T_INTEGER T_INTEGER MAX_ T_INTEGER 


{ approx.subdiv[miMIN] = $2; 
approx. subdiv [miMAX] $3; 
approx.max = $5; } 

S_approx_params SAMPLES T_INTEGER 

{ approx.subdiv[miMIN] = 0; 
approx.subdiv[miMAX] = 5; 
approx .max = $3; 


if (approx.style == miAPPROX_STYLE_FINE | | 


approx.style == miAPPROX_STYLE_FINE_NO_SMOOTHING) 


approx.subdiv[miMAX] = 7; } 


S_approx_params T_INTEGER T_INTEGER SAMPLES T_INTEGER 


{ approx.subdiv[miMIN] = $2; 
approx. subdiv [miMAX] $3; 
approx .max = $5; } 


: C_approx_params 


{ approx.subdiv[miMIN] = 0; 
approx.subdiv[miMAX] = 5; } 
C_approx_params T_INTEGER T_INTEGER 
{ approx.subdiv [miMIN] $2; 
approx. subdiv [miMAX] O33 J 


S_approx_param 
S_approx_param s_approx_params 


C_approx_param 
C_approx_param C_approx_params 


: X_approx_param 


PARAMETRIC floating floating 
{ approx.method 
approx.cnst [miCNST_UPARAM] = $2; 
approx.cnst [miCNST_VPARAM] = $3; } 
REGULAR PARAMETRIC floating floating 
{ approx.method 
approx.cnst [miCNST_UPARAM] = $3; 
approx. cnst [miCNST_VPARAM] $4; } 


miAPPROX_PARAMETRIC ; 


miAPPROX_REGULAR ; 
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c_approx_param 


X_approx_param 


REGULAR PARAMETRIC floating ’%’ floating ’%’ 
= miAPPROX_REGULAR_PERCENT ; 


{ approx. 


method 


approx.cnst [miCNST_UPARAM] = 


approx.cnst [miCNST_VPARAM] 


IMPLICIT 


{ approx. 


X_approx_param 


method 


PARAMETRIC floating 


{ approx. 


method 


approx.cnst [miCNST_UPARAM] = 
approx. cnst [miCNST_VPARAM] = 


REGULAR PARAMETRIC floating 


{ approx.method 


approx.cnst [miCNST_UPARAM] 


approx.cnst [miCNST_VPARAM] = 

REGULAR PARAMETRIC floating ’%’ 
{ approx.method 
approx. cnst [miCNST_UPARAM] = 

cnst [miCNST_VPARAM] - 


approx. 


: VIEW 


{ approx. 


OFFSCREEN 


{ approx. 


ANY 


{ approx. 


TREE 


{ approx. 


GRID 


{ approx. 


DELAUNAY 


{ approx. 


FINE 


{ approx. 


any 

style 
style 
style 


style 


FINE NOSMOOTHING 


{ approx. 


SHARP floating 


{ approx. 
LENGTH floating 


style = 


sharp 


{ approx.method 
approx.cnst [miCNST_LENGTH] = 
DISTANCE floating 
{ approx.method 
approx.cnst[miCNST_DISTANCE] = 


ANGLE floating 


{ approx.method 
approx.cnst [miCNST_ANGLE] = 


SPATIAL approx_view floating 


{ approx.method 
approx. cnst [miCNST_LENGTH] = 


$3 ; 
$5; } 


miAPPROX_ALGEBRAIC; } 


miAPPROX_PARAMETRIC; 
$2; 


miAPPROX_REGULAR; 
$3; 
iste 


= miAPPROX_REGULAR_PERCENT ; 


miTRUE; 


$3; 
100.0; } 


} 


miAPPROX_STYLE_TREE; } 


miAPPROX_STYLE_GRID; } 


miAPPROX_STYLE_DELAUNAY; } 


miAPPROX_STYLE_FINE; } 


$2<0? O: 


miAPPROX_STYLE_FINE_NO_SMOOTHING; } 


$2>17? 255: $2*255.;} 


miAPPROX_LDA; 


$2; } 


miAPPROX_LDA; 
$2; 5 


miAPPROX_LDA; 
$2; } 


miAPPROX_SPATIAL; 
a 
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approx_view 


S_approx_names 


sds_approx_names: 


d_approx_names 


C_approx_names 


Spc_approx_names: 


t_approx_names 


B Scene File Grammar 


CURVATURE approx_view floating floating 


{ approx.method miAPPROX_CURVATURE; 


approx.cnst[miCNST_DISTANCE] = $3; 
approx.cnst [miCNST_ANGLE] = $4; } 
GRADING floating 
{ approx.grading = $2; } 
VIEW 
{ approx.view_dep l= 1; } 
OFFSCREEN 
{ approx. view_dep |= 2; } 
: symbol 


{ mi_api_surface_approx($1, &approx); } 
S_approx_names symbol 
{ mi_api_surface_approx($2, &approx); } 


symbol 

{ mi_api_subdivsurf_approx($1, &approx); } 
sds_approx_names symbol 

{ mi_api_subdivsurf_approx($2, &approx); } 


: symbol 


{ mi_api_surface_approx_displace($1, &approx); } 
S_approx_names symbol 
{ mi_api_surface_approx_displace($2, &approx); } 


: symbol 


{ mi_api_curve_approx($1, &approx); } 
C_approx_names symbol 
{ mi_api_curve_approx($2, &approx); } 


symbol 

{ mi_api_spacecurve_approx($1, approx); } 
C_approx_names symbol 

{ mi_api_spacecurve_approx($2, &approx); } 


: symbol 


{ mi_api_surface_approx_trim($1, &approx); } 
t_approx_names symbol 
{ mi_api_surface_approx_trim($2, &approx); } 


B Scene File Grammar 


* user-interface 


gui_elems 


gui_elem 


gui_controls 


gui_control 


gui_attr_list 


gui_attr 


: GUI opt_symbol 


{ mi_api_gui_begin($2); } 
*(? god atir List. +)? "4? gud controls *}? 
{ mi_api_gui_end(); } 
GUI opt_symbol 
{ mi_api_gui_begin($2); } 
‘4? gat controle. ? }? 
{ mi_api_gui_end(); } 


gui_elem gui_elems 


‘<<? 903 ettr. list *)? 
i 

{ mi_api_gui_push(); } 
gui_controls *}" 

{ mi_api_gui_pop(); } 


gui_control gui_controls 


: CONTROL symbol opt_symbol 


{ mi_api_gui_control_begin($37$2:0, $37$3:$2); } 
gui_elems 
{ mi_api_gui_control_end(); } 


d ? 
> 


gui_attr 
gui_attr ’,’ gui_attr_list 


: symbol 


{ mi_api_gui_attr($1, miNTYPES, 0); } 
symbol boolean 

{ mi_api_gui_attr($1, miTYPE_BOOLEAN, 1, $2); } 
symbol floating 

{ mi_api_gui_attr($1, miTYPE_SCALAR, 1, $2); } 
symbol floating floating 

{ mi_api_gui_attr($1, miTYPE_SCALAR, 2, $2, $3); } 
symbol floating floating floating 

{ mi_api_gui_attr($1, miTYPE_SCALAR, 3, $2, $3, $4); } 
symbol floating floating floating floating 

{ mi_api_gui_attr($1, miTYPE_SCALAR, 4, $2,$3,$4,$5); } 
symbol symbol 
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{ mi_api_gui_attr($1, miTYPE_STRING, 1, $2); } 
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Catmull-Clark scheme, 154 
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caustic filtering, 97 

caustics, 7, 13, 41, 96—98, 115, 117, 120, 125, 
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code, 74, 186, 281 

coherent noise, 360 

color, 33, 34 

color bleeding, 97, 127, 329 

color clipping, 34, 101, 343, 711 

color profile, 468 

color temperature, 469 

color texture type, 62 

color type, 62 

command, 59, 60, 74 

command line option, 35, 709, 728 

comment, 60 
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compiler, 186, 186 

concave polygon, 134 

concurrency, 393 

conditionals, 78, 80, 702 

connection, 11, 12, 137, 148, 148, 168 

contour, 14, 41, 73, 102, 103, 107, 115, 289 

contour contrast shader, 41, 73, 102, 103, 217, 
224, 290, 292, 399 

contour line, 390, 391 

contour output shader, 107, 295, 390 

contours, fast, 178 

contour shader, 14, 41, 193, 224, 289, 290, 
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contour store shader, 41, 63, 73, 102, 103, 
217, 224, 290, 290, 399, 516 

contrast, 85, 712 

control point, 130, 140 
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curvature approximation, 136, 162 
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data, 84 

database access, 320 
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debugging shaders, 189 
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depth, 114 

depth frame buffer, 34, 345 

depth of field, 29 
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desaturation, 34, 101, 343, 712 

detail shadowmap, 17, 92, 121, 122, 513, 514, 
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diagnostic mode, 103, 712 

diffuse color, 19, 22, 114, 226, 227, 238, 265 

diffuse reflection, 335, 338, 341 

diffuse transmission, 335, 339 
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directional light, 118, 118 
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displacement approximation, 162 

displacement map, 12, 17, 22, 22, 83, 89, 90, 
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dithering, 101, 343, 713 
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echo, 75, 713 
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efficiency, 392, 394 
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emitter shader, 192, 206, 328, 512 
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filter, 87 

finalgather, 130, 169, 170 
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fragment shader, 419, 419, 421-423, 426, 428, 
429, 431, 433, 435 
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hair, 150, 244, 289, 483, 696 

hair object, 535 

hardware rendering, 52, 88, 418, 418, 718 
hardware shader, 418 

header files, 307 
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high dynamic range, 34, 36-39, 106, 663, 664 
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label, 34, 114, 129, 346 
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lens effects, 29, 29 
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memory leaks, 403 
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mental matter, 12, 134, 154 
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miHOST, 396 
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mip-map texture, 20, 23, 25, 113, 370, 463 
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Mitchell, 87 

mi THREAD, 396 
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miVPU, 396 
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named shader, 67, 67, 84 
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normal transformation, 357 
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numerical precision, 209, 238 
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object, 84, 124, 126 
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parallelism, 2, 7 
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Perlin noise, 360, 360, 406 
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phenomenon root, 72, 441 
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point transformation, 352, 355 
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ray offset, 324, 326 
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557, 592, 696, 701, 724, 727 
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reflection map, 17, 22, 201 

refraction, 2, 25, 30, 32, 44-46, 91, 93, 114, 
115, 126,. 170, 207, 220, 238, 241, 
251, Seen? ee 
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renderpass preprocessing shader, 306 
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RGBE, 34, 36, 38, 39, 106, 663 

root instance group, 84, 105, 170, 174 
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sample combination, 39 

sample interpolation, 39, 281 

sample padding, 39 

sample rate, 85, 86, 712, 724 

sampling, 85, 86, 290, 292 
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scalar map, 19, 22 
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scalar type, 61 
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23/, 259 

shader, 3, 60, 64, 185 
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shader call, 76, 316 
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shadow map, 16, 33, 92, 117, 120, 221, 514, 
724, 725 
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shell, 76 
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special point, 12, 139, 140, 145 

specular color, 226, 227, 238, 265 

specular reflection, 335, 338, 340 

specular transmission, 335, 339, 341 

spot light, 118, 121, 260 

startup file, 79, 81, 428, 574, 577, 596, 736 

state shader, 103, 193, 276, 399, 566 

state variables, 79, 198, 200, 202, 204, 208, 
211-215, 321 
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string type, 62 
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tag, 320 

tagged flag, 116, 127, 134, 139, 171, 381, 490 

tag pinning, 321 

tag size, 321 

tag type, 320 

tag unpinning, 321 

task size, 93, 104, 727, 736 

Taylor, 10, 136, 138, 138 

texture, 17, 19, 20, 83, 112, 114, 211, 238, 343 
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texture surface, 20, 139, 142 
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thread numbers, 396 
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time contrast, 31, 85, 727 

tone mapping, 346 
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transform type, 62 
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transparency, 19, 83, 91, 93, 114, 115, 170, 
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transparency ray, 93, 126, 207, 219, 220, 557 
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uniform variable, 419, 419, 420, 426, 433, 433 
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user data block, 123, 466, 466, 467 

user frame buffer, 102, 107, 238, 382, 383 
user pointer, 199, 203, 212, 232, 390, 405, 516 
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variable, 78 

vector, 130 

vector functions, 348 
vector index, 131 

vector sharing, 131 
vector texture type, 62 
vector transformation, 352, 357 
vector type, 61 

verbatim textures, 112 
verbose message, 75, 727 
vertex, 130, 130 
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vertex index, 131, 134 
vertex order, 135 
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view dependency for final gathering, 223 

view-dependent approximation, 11, 23, 110, 
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viewing plane, 109, 110, 111, 710, 711, 717 
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use restrictions and that may disable functionality of the Software and prevent access to data 
using the Software. 


Obligations. Unless otherwise specifically agreed by mental images in writing, you: (a) shall not 
copy, distribute, transfer, loan or otherwise provide the Software to any third party outside your 
own organization; (b) shall not reverse compile, reverse engineer or disassemble the Software 
(except solely in the circumstances where you are required to be permitted to do so under 
applicable local law); (c) may not modify, disable, attempt to circumvent or otherwise interfere 
with any License Enforcement Mechanisms, and acknowledge that any attempt to do so may be 
a violation of applicable law; and (d) shall display, and shall not alter or remove, mental images’ 
copyright and other proprietary notices. 


Ownership. You acknowledge and agree that the Software is owned and copyrighted by mental 
images or its third party suppliers. Your license confers no title or ownership in the Software and 
is not a sale of any rights in the Software. All ownership rights remain in mental images or its 
third party suppliers, as the case may be. 


NO WARRANTY AND NO LIABILITY. Due to the purpose that the Software is being 
supplied to you (evaluation for purchase or for your personal educational purposes only), mental 
images makes no warranties whatsoever as to the operational performance of the Software. 
mental images will not provide any support or bug-fixes for the Software. TO THE MAXIMUM 
EXTENT PERMITTED BY LAW, MENTAL IMAGES DISCLAIMS ALL WARRANTIES, 
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EXPRESS OR IMPLIED. IN PARTICULAR, THE SOFTWARE IS PROVIDED “AS IS”, 
WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION THE 
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE 
AND NON-INFRINGEMENT. The entire risk as to the quality and performance of the 
Software is borne by you. Should the Software prove defective, you and not mental images assume 
the entire cost of any service and repair. This disclaimer of warranty constitutes an essential part 
of this Agreement. SOME JURISDICTIONS DO NOT ALLOW EXCLUSIONS OF AN 
IMPLIED WARRANTY, SO THIS DISCLAIMER MAY NOT APPLY TO YOU AND YOU 
MAY HAVE OTHER LEGAL RIGHTS THAT VARY BY JURISDICTION. 


Because software is inherently complex and may not be completely free of errors, you are advised 
to verify and back up your work. Additionally, mental images does not guarantee compatibility 
between the Software and any non-evaluation or future versions of the Software. 


LIMITATIONS ON LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY 
LAW, UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, TORT, 
CONTRACT, OR OTHERWISE, SHALL MENTAL IMAGES BE LIABLE TO YOU 
OR ANY OTHER PERSON FOR ANY MONEY DAMAGES, WHETHER DIRECT, 
INDIRECT, SPECIAL, INCIDENTAL, COVER, RELIANCE OR CONSEQUENTIAL 
DAMAGES, EVEN IF MENTAL IMAGES SHALL HAVE BEEN INFORMED OF THE 
POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY. IN 
THE EVENT THAT NOTWITHSTANDING THE FOREGOING, MENTAL IMAGES IS 
FOUND LIABLE TO YOU FOR DAMAGES FROM ANY CAUSE WHATSOEVER, AND 
REGARDLESS OF THE FORM OF THE ACTION (WHETHER IN CONTRACT, TORT 
(INCLUDING NEGLIGENCE), PRODUCT LIABILITY OR OTHERWISE), MENTAL 
IMAGES’ LIABILITY TO YOU WILL BE LIMITED TO THE GREATER OF US$25 
OR THE AMOUNT YOU PAID FOR THE SOFTWARE. SOME JURISDICTIONS 
DO NOT ALLOW THE EXCLUSION OR LIMITATION OF INCIDENTAL OR 
CONSEQUENTIAL DAMAGES, SO THIS LIMITATION AND EXCLUSION MAY NOT 
APPLY TO YOu. 


Export Controls. None of the Software or underlying information or technology may be 
downloaded or otherwise exported or reexported in violation of United States export control law, 
including to anyone on the U.S. Treasury Department’s list of Specially Designated Nationals 
or the U.S. Commerce Department’s Table of Denial Orders. By downloading or using the 
Software, you are agreeing to the foregoing and you are representing and warranting that you are 
not located in, under the control of, or a national or resident of any country to which such export 
is so prohibited or on any such list. In addition, you are responsible for complying with any local 
laws in your jurisdiction which may impact your right to import, export or use the Software, and 
you represent that you have complied with any regulations or registration procedures required 
by applicable law to make this license enforceable. 


U.S. Government End Users. The Software is a “commercial item,” as that term is defined in 
48 C.E.R. 12.101 (Oct. 1995), consisting of “commercial computer software” and “commercial 
computer software documentation,” as such terms are used in 48 C.ER. 12.212 (Sept. 1995). 
Consistent with 48 C.ER. 12.212 and 48 C.ER. 227.7202-1 through 227.7202-4 (June 1995), all 
U.S. Government End Users acquire the Software with only those rights set forth herein 
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Term. Your license under this Agreement is effective permanently unless terminated. Either you 
or mental images may terminate this license at any time. Upon any such termination or expiration, 
you must discontinue all use of the Software, and immediately destroy the Software together with 
all copies. The provisions of this Agreement (other than your license to use the Software) shall 
survive the termination of the license, or the termination or expiration of this Agreement. 


Controlling Law and Severability. This Agreement constitutes the entire agreement between 
you and mental images with reference to this transaction. This Agreement will be governed by the 
laws of the Commonwealth of Massachusetts, USA, except for that body dealing with conflicts of 
law. The application to this Agreement of the United Nations Convention on Contracts for the 
International Sale of Goods is hereby expressly excluded. In the event of any dispute involving 
this Agreement, mental images and you each consent to exclusive jurisdiction and venue in either 
the state or federal courts in the Commonwealth of Massachusetts and agrees that the prevailing 
party shall be entitled to its reasonable attorney fees and costs. In the event any provision of 
this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified 
so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in 
full force and effect. No decision, action or inaction by mental images shall be construed to be a 
waiver of any rights or remedies available to it. 
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Rendering with mental ray® 


Third, completely revised edition. 

2005. XV, 626 pages. 195 figures (48 colored).With CD-ROM. 
Softcover EUR 69,- 

(Recommended retail price) 

Net-price subject to local VAT. £) SpringerWienNewYork 
ISBN 3-211-22875-6 

mental ray Handbooks, Volume 1 a 


Written by the mental ray software project leader, this book gives a general intro- 
duction into rendering with mental ray, as well as step-by-step recipes for creat- 
ing advanced effects and tips and tricks for professional users. A comprehensive 
definition of mental ray’s scene description language and the standard shader 
libraries are included as the basis for all examples. 

The third, completely revised edition covers the latest version of the new genera- 
tion of mental ray, version 3.4. A CD with a fully programmable demo version of 
the software, together with example scene data and shaders that are described 
in the book, is enclosed. 


From the contents: 


Introduction * Overview * Scene Construction * Cameras * Surface Shading ¢ Light 
and Shadow * Volume Rendering * Caustics and Global Illumination * Motion Blur» 
Hardware Rendering * Contours * Shaders and Phenomena * Postprocessing and 
Image Output * Geometric Objects * Instancing and Grouping * Inheritance » 
Incremental Changes and Animations * Using and Creating Shader Libraries » Par- 
allelism * The Options Block + The Architecture of mental ray 3.x * Quality and Per- 
formance Tuning * Troubleshooting * Color Plates » Command Line Options * The 
Sphere and Utah Teapot Models « Base Shaders * Physics Shaders * Contour Shaders * 
Glossary/Bibliography/Index 


D) SpringerWien NewYork 


P.O. Box 89, Sachsenplatz 4-6, 1201 Vienna, Austria, Fax +43.1.330 24 26, books@springer.at, springer.at 

HaberstraBe 7,69126 Heidelberg, Germany, Fax +49.6221.345-4229, SDC-bookorder@springer-sbm.com, springeronline.com 
P.O. Box 2485, Secaucus, NJ 07096-2485, USA, Fax +1.201.348-4505, orders@springer-ny.com, springeronline.com 

Eastern Book Service, 3-13, Hongo 3-chome, Bunkyo-ku, Tokyo 113, Japan, Fax +81.3.38 18 08 64, orders@svt-ebs.co.jp 

Prices are subject to change without notice. All errors and omissions excepted. 
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SpringerComputerScience 


Stefanie Hahmann, 
Guido Brunnett, 
Gerald Farin, 

Ron Goldman (eds.) 


Geometric Modelling 


Dagstuhl 2002 


2004. VIII, 246 pages. 104 figures. 

Softcover EUR 79,- 

(Recommended retail price) 

Net-price subject to local VAT. 

(Special Edition of "Computing", Vol. 72/1-2, 2004) 
ISBN 3-211-20818-6 


In 19 articles presented by leading experts in the field of geometric modelling the 
state-of-the-art on representing, modeling, and analyzing curves, surfaces as well 
as other 3-dimensional geometry is given. The range of applications include 
CAD/CAM-systems, computer graphics, scientific visualization, virtual reality, simu- 
lation and medical imaging. The content of this book is based on selected lectures 
given at a workshop held at IBFl Schloss Dagstuhl, Germany. 


Topics treated are: 

— curve and surface modelling 

—non-manifold modelling in CAD 

— multiresolution analysis of complex geometric models 
— surface reconstruction 

— variational design 

— computational geometry of curves and surfaces 

- 3D meshing 

— geometric modelling for scientific visualization 

— geometric models for biomedical applications 


g) SpringerWien NewYork 


P.O. Box 89, Sachsenplatz 4-6, 1201 Vienna, Austria, Fax +43.1.330 24 26, books@springer.at, springer.at 

HaberstraBe 7,69126 Heidelberg, Germany, Fax +49.6221.345-4229, SDC-bookorder@springer-sbm.com, springeronline.com 
P.O. Box 2485, Secaucus, NJ 07096-2485, USA, Fax +1.201.348-4505, orders@springer-ny.com, springeronline.com 

Eastern Book Service, 3-13, Hongo 3-chome, Bunkyo-ku, Tokyo 113, Japan, Fax +81.3.38 18 08 64, orders@svt-ebs.co.jp 

Prices are subject to change without notice. All errors and omissions excepted. 
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Springer and the Environment 


WE AT SPRINGER FIRMLY BELIEVE THAT AN _ INTER- 
national science publisher has a special obligation to 
the environment, and our corporate policies consis- 
tently reflect this conviction. 


WE ALSO EXPECT OUR BUSINESS PARTNERS — PRINTERS, 
paper mills, packaging manufacturers, etc.—to commit 
themselves to using environmentally friendly mate- 
rials and production processes. 


THE PAPER IN THIS BOOK IS MADE FROM NO-CHLORINE 
pulp and is acid free, in conformance with inter- 
national standards for paper permanency. 


This book is the definitive reference 
manual for mental ray, version 3.4. 

It starts with a brief overview of the 
features of mental ray and continues 
with the specification of the mental ray 
scene description language, the mental 
ray shader interface, and the integration 
interface for third-party applications. 
All material is presented in reference 
form, organized by grammar elements 
and C function call, rather than by 
feature set. The book is intended for 
translator writers, shader writers, and 
integrators who are familiar with the C 
and C++ programming languages. 

The enclosed CD contains a demo 
version of the mental ray standalone 
and the mental ray library, as well as 
example shaders with source code and 
demo scenes, for a variety of computer 
platforms. 


ISSN 1438-9835 
ISBN 3-211-24484-0 
springer.at 
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